Vvidget Code Reference Manual

Vvidget Code > API > iOS > 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.


Linkage

Add the Dictionary Constructor functionality to your project by adding all the headers in /Library/Vvidget/ios/include to your project and one of the libraries referenced below for a specific build Configuration.

Definition:/Library/Vvidget/ios/include/VvidgetCodeDictionaryConstructor.h
Device Implementation:/Library/Vvidget/ios/lib/device/libVvidget.a
Simulator Implementation:/Library/Vvidget/ios/lib/simulator/libVvidget.a


Method Definitions

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:

VvidgetCodeDictionaryConstructor *constructor;
constructor = [[VvidgetCodeDictionaryConstructor alloc] init];

The newly constructed object is assigned to the symbol constructor and that is the symbol you refer to in subsequent calling code.

- (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).

[constructor VC_reset];

- (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.

[constructor VC_append_key:"chart_type" string_value:@"line"];

- (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:

char *buffer;
unsigned buffer_length;
buffer = [constructor VC_working_bytes_with_length:1024];
/* add bytes to buffer probably using sprintf() or similar and keep track of buffer_length. */
[constructor VC_append_key:"data_values" char_c_array_value:buffer length:buffer_length];

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.


Actual Use

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.




© Copyright 1993-2011 by VVimaging, Inc. (VVI); All Rights Reserved. Please email support@vvi.com with any comments you have concerning this documentation. See Legal for trademark and legal information.