Remoto - VFS
|
Utility functions for javascript clients. More...
#include "remoto!stdlib:js/include/utils.js"
Public Member Functions | |
base64Encode (o) | |
Encode a JSON object using base64, replacing '/' characters with '_'. More... | |
bound (min, n, max) | |
Return a number where n is bounded by [min,max]. More... | |
cleanPath (path) | |
Clean and normalize a resource path. More... | |
copyObject (source, dest) | |
Create a deep copy of a JSON object, extending the destination object recursively. More... | |
dirNameFromPath (p) | |
Retrieve the directory portion of a path. More... | |
equalObjects (o1, o2) | |
Do a single-level pass on two objects for key->value equality. More... | |
exitFullScreen () | |
Request an exit from fullscreen mode. More... | |
extendBBox (b, a) | |
Extend bounding box b by an amount a. More... | |
fileNameFromPath (p, orDirIfNeeded) | |
Retrieve the last part of a file path. More... | |
humanReadableSize (s) | |
Calculate a human-readable size from a number of bytes. More... | |
isArray (a) | |
Determine if an object is a javascript array. More... | |
isFullScreen () | |
Detect if the page is in fullscreen mode. More... | |
isInstanceOf (o, t) | |
Check if an object is of a chosen type. More... | |
keyCount (o) | |
Return the number of keys in an object. More... | |
keyCountFiltered (o, f) | |
Return the number of keys on an object that match a filter. More... | |
keyFromValue (o, val) | |
Given a value, retrieve the key for a potential entry in an object. More... | |
randInt (min, max) | |
Return a pseudo-random value in the range of [min,max]. More... | |
requestFullScreen () | |
Issue a request to enter fullscreen state. More... | |
resolveContextValues (o, ctx) | |
Recursively resolve any context values in an object. More... | |
setAttr (e, a) | |
A DOM manipulation function to work around a jQuery bug. More... | |
sortObjectByMemberAttribute (o, attr) | |
Sort an object by the value of an attribute of members of the object. More... | |
toggleFullScreen () | |
Toggle the fullscreen state of the page. More... | |
uuid () | |
Generate a universally unique identifier. More... | |
Utility functions for javascript clients.
The library includes tools for manipulating paths, diffs, objects, fullscreen state, and a few math functions.
All of these functions are free-standing and act like static members of namespace 'utils'.
A simple use case:
base64Encode | ( | o | ) |
Encode a JSON object using base64, replacing '/' characters with '_'.
o | The object to encode |
Qt uses RFC 2045, which uses a '/' for value 63. We want to be able to use a base64 string as a path component, which cannot contain '/'.
bound | ( | min, | |
n, | |||
max | |||
) |
Return a number where n is bounded by [min,max].
min | The minimum value |
n | The value |
max | The maximum value |
cleanPath | ( | path | ) |
Clean and normalize a resource path.
path | The path to examine |
Remove all duplicate directory separators '/' and remove them from the beginning and end of a path to produce a path that can be used safely with the VFS as well as a client and maintain uniformity.
Because paths are used as IDs, they need to be well-formed if path math is performed (appending directories, filenames, removing them, etc.).
copyObject | ( | source, | |
dest | |||
) |
Create a deep copy of a JSON object, extending the destination object recursively.
source | Copy from this object |
dest | Copy to this object |
If the destination object is missing, a new one is created. This function will also copy getters and setters, and works on classes, functions, and arrays.
The function is recursive; it calls itself to complete the deep copy. This means that if very deep objects are submitted, they may exceed the call stack limit, although this would be an exotic case.
This is one of the basic mechanisms being used to apply diffs and emulate subclasses in javascript. The concept is essentially the same as jQuery's extend().
It can be useful at times to make a deep copy of an object without a destination: copyObject(o)
, which will return a new object instance matching the source, but as an entirely new object.
dirNameFromPath | ( | p | ) |
Retrieve the directory portion of a path.
p | The resource path |
This is mostly useful for creating contexts. If the path provided is not a string "DIRNAME" is returned, and an error printed.
equalObjects | ( | o1, | |
o2 | |||
) |
Do a single-level pass on two objects for key->value equality.
o1 | The first object |
o2 | The second object |
Values are compared using '!==', and only first level keys are compared. If an object has complex members, it will probably fail to prove equal to another object.
exitFullScreen | ( | ) |
Request an exit from fullscreen mode.
extendBBox | ( | b, | |
a | |||
) |
Extend bounding box b by an amount a.
b | The bounding box object, expressed as {x,y,width,height} values |
a | The amount to extend |
fileNameFromPath | ( | p, | |
orDirIfNeeded | |||
) |
Retrieve the last part of a file path.
p | The resource path |
orDirIfNeeded | Optionally allow the last part to be the containing directory if it ends with a '/'. |
If the path provided is not a string, "FILENAME" is returned, and an error printed.
humanReadableSize | ( | s | ) |
Calculate a human-readable size from a number of bytes.
s | The size, in bytes |
isArray | ( | a | ) |
Determine if an object is a javascript array.
a | The object/array to check. |
Detecting if an object is an array is a much debated topic for JavaScript. Newer versions will resolve this. For now, we use the test:
...which generally works.
isFullScreen | ( | ) |
Detect if the page is in fullscreen mode.
isInstanceOf | ( | o, | |
t | |||
) |
Check if an object is of a chosen type.
o | The object to check. |
t | A single type or an array of types to check. |
keyCount | ( | o | ) |
Return the number of keys in an object.
o | The object to check. |
Return a count of 0 if the object is bad, otherwise return Object.keys(o).length.
keyCountFiltered | ( | o, | |
f | |||
) |
Return the number of keys on an object that match a filter.
o | The object to check. |
f | The filter to apply. This function should return a boolean value. |
A missing filter will match all keys.
keyFromValue | ( | o, | |
val | |||
) |
Given a value, retrieve the key for a potential entry in an object.
o | The object to check. |
val | The value to compare to. |
The value comparison is done with '===', so complex objects will not be deeply compared.
randInt | ( | min, | |
max | |||
) |
Return a pseudo-random value in the range of [min,max].
min | The beginning of the range. |
max | The end of the range. |
This value is calculated as: Math.floor(Math.random()*(max-min+1)+min)
requestFullScreen | ( | ) |
Issue a request to enter fullscreen state.
resolveContextValues | ( | o, | |
ctx | |||
) |
Recursively resolve any context values in an object.
o | The object to check |
ctx | The context to use |
Context values may be provided by the server to prevent using fixed paths for nodes. Those values need to be resolved to arrive at complete paths for VFS_request operations, for instance. Context values will be in the form "%value%"
and will be part of string values only.
This function will resolve strings with context values and also recurse into members of the object to resolve those as well, using the same context.
Keys can also contain tokens.
Because a value may resolve to another context value, the maximum replacement depth is fixed to 10. If a context value can't be resolved, it will be left in place.
setAttr | ( | e, | |
a | |||
) |
A DOM manipulation function to work around a jQuery bug.
e | The element to modify. |
a | An object of attributes to set. |
This is a workaround for DOM manipulation, namely for SVG objects, where attribute names should not be set to lower case. This function will maintain case when setting attributes.
sortObjectByMemberAttribute | ( | o, | |
attr | |||
) |
Sort an object by the value of an attribute of members of the object.
o | The JSON object to sort |
attr | The attribute to sort on |
This is generally used to sort form fields, where serialized JSON will re-alphabetize field names but we want to present them in some other order. A more advanced version of this would allow attr to be a function, however this hasn't proved to be needed yet.
The resulting array will remember keys by attaching a __key field to each entry:
toggleFullScreen | ( | ) |
Toggle the fullscreen state of the page.
uuid | ( | ) |
Generate a universally unique identifier.
This is based on an algorithm found here: http://stackoverflow.com/questions/105034/how-to-create-a-guid-uuid-in-javascript , but modified for 16 hex digits.