Vvidget Code > API > Mac OS X > Embedded > Dictionary Constructor
The Dictionary Constructor is defined by the VvidgetCodeDictionaryConstructor class. An instance of that class is used to aid in the construction of a Dictionary which defines a graph.
Add the Dictionary Constructor functionality to your project by adding all the headers in /Library/Vvidget/macosx/include to your project and one of the frameworks referenced below.
| Definition: | /Library/Vvidget/macosx/include/VvidgetCodeDictionaryConstructor.h |
| Shared Frameworks: | /Library/Frameworks/Vvidget_*.framework |
| Embedded Frameworks: | /Library/Vvidget/EmbeddedFrameworks/Vvidget_*.framework |
If you use the Embedded Frameworks then you will need to add a build copy phase to your project to copy the Vvidget Frameworks into your application bundle. See Deploy for details.
The following defines each method that is used with an object (instance) of the VvidgetCodeDictionaryConstructor type.
- (id)init
|
You will need to make at least one dictionary constructor for your application. The following makes a dictionary constructor:
The newly made object is assigned to the symbol |
- (void)VC_reset
|
Once you use a dictionary constructor to make a graph then its state (key and value pairs) is complete. To use it again you must reset it (or alternatively release it and make a new one). The following resets the dictionary constructor to its initial state (the state it had when you first created it).
|
- (void)VC_append_key:(const char *)a_key_c_string string_value:(NSString *)a_value
|
After making (or resetting) a constructor you will need to add keys and values to it. This method adds the key a_key_c_string with value a_value of type NSString to the constructor. For example, the following adds an entry to the dictionary which sets the state of the dictionary so that it produces a line chart.
|
- (void)VC_append_key:(const char *)a_key_c_string data_value:(NSData *)a_value
| This method adds the key a_key_c_string with value a_value of type NSData to the constructor. a_value can contain any value of bytes, but it must be something specific to the key for it to make sense. Typically a_value is a C string of ASCII encoded numbers. |
- (void)VC_append_key:(const char *)a_key_c_string char_c_array_value:(const char *)a_value length:(unsigned)a_length
| This method adds the key a_key_c_string with value a_value of type const char * with length a_length to the constructor. |
- (void)VC_append_key:(const char *)a_key_c_string unsigned_value:(unsigned)a_value
| This method adds the key a_key_c_string with value a_value of type unsigned to the constructor. |
- (void)VC_append_key:(const char *)a_key_c_string double_value:(double)a_value
| This method adds the key a_key_c_string with value a_value of type double to the constructor. |
- (void)dealloc
| This method deallocates the constructor. |
- (char *)VC_working_bytes_with_length:(unsigned)a_length
|
This method returns a memory region that is a_length bytes long. This method helps conserve memory and makes constructor use more efficient. Use it as follows:
This method is useful because the constructor typically spans scope (is an ivar of an object and not an auto variable on a method stack) and thus the returned bytes need not be alloc() and free() within each method that uses the constructor and its associated method that utilizes bytes of data. |
The following is a complete calling sequence of a dictionary constructor and makes a line graph state in dictionary form.
constructor = [[VvidgetCodeDictionaryConstructor alloc] init];
[constructor VC_append_key:"pvs_version" unsigned_value:1U];
[constructor VC_append_key:"vvidgetcode_deployment_license" string_value:@"embedded 1d65ch78f09aadR06464fY6"];
[constructor VC_append_key:"image_maker" string_value:@"chart"];
[constructor VC_append_key:"chart_type" string_value:@"line"];
[constructor VC_append_key:"chart_subtype" string_value:@"linear"];
[constructor VC_append_key:"chart_format_type" string_value:@"default"];
[constructor VC_append_key:"title" string_value:@"Vvidget Code Example Project"];
[constructor VC_append_key:"x_title" string_value:@"My X Title"];
[constructor VC_append_key:"y_title" string_value:@"My Y Title"];
[constructor VC_append_key:"data_1" string_value:"1 2 2 4 3 6"];
[constructor VC_append_key:"line_color" string_value:@"0000FF"];
As you can see, the API for the constructor is just enough to permit the function of defining a key value state and nothing more. In other words, the API does not define a graph, rather it simply defines a handful of methods to make a dictionary. For definitions of state see the section Dictionary. Now that you have a fully setup constructor you will need to do something with it. The prescription is to inform a parser to decode the dictionary into an object graph that can be imaged (drawn) to your application. You do that with this call:
[dictionary_parser VC_update_using_dictionary_constructor:constructor];
At this point, the explanation of the dictionary constructor is complete. The dictionary constructor simply appends keys and values to itself and the parser uses that dictionary. Consult Dictionary Parser to learn about parsing a dictionary.
| Please help improve this documentation. If a section is hard to understand, there is a typo, you would like a new section added, or you detect any other improvement that can be made then please email support@vvi.com with your information. |