4.20.3.1 Parameter Delivery

This section describes automatic parameter delivery, which provides a mechanism for extracting component parameters from a window definition.

In AWS, all windows are defined by a window definition. There may be multiple definitions in a file, or you may have multiple files. That's all up to the end user. For a component writer, however, you need to be able to get at this information. Furthermore, you need to be able to get the information for the window that's being created, and for the current instance of the component. How does that happen?

It's very easy, actually. The window manager knows everything about everything, and it particularly knows where the component is in the window's setup process. You should only need to get your parameters once per creation of a window, and that happens at setup time.

Each component must override a function called Setup() in `awsComponent'. You should always called the base awsComponent::Setup() first, because there is some important work for it to do. You must never release or delete the parameters passed in to you, because they are not yours. You should never store the settings parameter, because it is only on loan and strange things may happen to it. Next, you are free to do whatever setup your component needs. This is primarily accomplished by using the GetBlah() functions of the preference manager. The Setup() function is passed two important parameters: a pointer to the window manager, and a pointer to the current settings container that contains all the settings for this instance of this component. The prototype for the setup function is as follows:

bool awsComponent::Setup(iAws* wmgr, awsComponentNode *settings)

The default Setup() in `awsComponent' sets an internal variable that stores the pointer to the window manager, which may then be retrieved afterward from the accessor function WindowManager(). The first statement in a setup function should always be:

if (!awsComponent::Setup(wmgr, settings))
  return false;

This lets the lower level setup code do some important initialization, and also keeps us from proceeding if something cataclysmic happens during initial setup. Returning `false' from the Setup() function at any time gracefully aborts construction of the component. It does not, however, abort construction of the entire container or window. It does abort construction of any children this component may have.

After the initial call to the base version of Setup(), you may do whatever you like. It is common to retrieve any important settings for your component here. For example, the base `awsComponent' retrieves the component's frame rectangle by performing the following:

iAwsPrefs *pm = WindowManager()->GetPrefMgr();
pm->GetRect(settings, "Frame", frame);

The preference manager supports two other versions of this command, altogether providing GetInt(), GetRect(), and GetString(). The first parameter is always provided for you: it is the settings container passed as a parameter. The second parameter is the text name of the attribute you wish to query, like `Frame' or `Style', etc. The final parameter is a variable of the type corresponding to the function, in which the results will be stored. For GetInt() this is always a signed integer, for GetRect() this is a `csRect' structure, and for GetString() this is an `iString' pointer.

If your component needs to get information about the default skin, it can do so using some other, very similar functions for the skin definition:

• LookupIntKey()
• LookupRectKey()
• LookupStringKey()
• LookupRGBKey()

These functions operate in a fashion identical to the GetBlah() functions, except that they know where their information is coming from, so they don't need a settings parameter. Also, LookupRGBKey() requires a reference to three value parameters: red, green, and blue in that order. Each is an unsigned character. Note that the preference manager also supports a Get() for colors, textures, and fonts. It is preferred to use these functions for actually getting those resources for use. Please consult the API reference for `awsPreferenceManager' for further information on those functions.

Once you have finished your setup process, you should always exit by returning `true'. This means that everything went well and you are ready to work.

This document was generated using texi2html 1.76.