![]() | Components and Event/Slot Scripting |
Prev | Next |
Earlier, this manual described how to incorporate preconfigured components, such as buttons and navigation tools, into forms and reports. These components were taken from those that are distributed as part of Rekall. However, Rekall also provides the means to construct your own components, which you can then use as often as you need.
This chapter is divided into four main parts. The first part describes the basics of building your own components. This does not involve any scripting; although this limits the level of functionality that you can achieve, it can still be used to provide a useful set of components. If you have no intention of writing any scripts of your own, you can skip the second and third parts of this chapter.
The second part describes the Event/Slot mechanism that Rekall provides. Although the use of this mechanism is not restricted to reusable components (it can be used anywhere in a form or report), its major use is with reusable components, since it provides a way of bundling a set of objects which will be used in a form or report together with the code that is needed to make use of them.
The third part then gives some examples of constructing resuable components which make use of the event/slot mechanism.
The fourth part discusses linking components, as opposed to pasting them.
The fifth part describes how you can directly invoke events and slots from script code, and how you can use unattached slots as a way of associating arbitrary code with objects (in effect giving methods to Rekall objects like buttons or fields).
Before going any futher, it is worth describing where Rekall can store components. There are three places. Firstly, there is the stock component set that comes with the Rekall distribution; secondly, components can be stored inside databases (just like forms and reports); and thirdly, they can be stored in a local directory (on Linux this is $HOME/.rekall/components. Normally, any components that you create yourself would be stored in a database or locally; storing in the database would be appropriate if you want to share them between all users of the database, while locally would be appropriate for your own personal components [57].
If you want you can store your components with the stock components, since stock components are just stored in files in a known directory, but (on Linux) you would normally need root access to do this, and they might be lost when upgrading - be warned.
There are two ways to go about rolling your own reusable components [58], either by saving one or more objects from an existing form or report, or by designing from scratch. Since creation of forms and reports has been described in earlier chapters, the former is described first.
At its simplest, creating a component from a form or report is as simple as right-clicking on an object and selecting Save as component, or selecting several objects, and then using the Save as component entry in the Edit menu. In either case, you will get the dialog shown below:
The top text box is used to enter a name for the component, while the combobox selects the place to store it. This will show each server database (including the !Files entry), plus Save to file. Selecting the latter and clicking OK will bring up a standard file dialog [59]. The comment area can be used to enter any comment, which will actually be saved as the notes propertly of the component. This text will appear under the Description tab of the component selection dialog that appears when you paste a component.
One thing to note is that all components are categorised as either form components or report components. A component that is created from a form is categorised as the former and can only be pasted into a form, and similarly for reports. This is necessary since, although some objects (such as labels) can appear in both forms and reports, there are many (possibly most) cases where creating a component from one and pasting it into the other would not be a good idea.
When you save an object as a component, the object is positioned in the component at position (10,10) and the component is sized to be just 10 pixels wider, and 10 pixels higher, than is strictly needed. If you save mutiple objects, then they maintain their relative positions, but the top-left one is similarly moved to (10,10), and the component is made (10,10) pixels larger. There is no particular reason for these values, other than for convenience if you later edit the component.
Once you have a created a component this way, unless it was saved to a local file, it will appear under the Components tab of the main database window, just as do forms and reports. From there you can edit it further.
The advantage of creating a component from objects in an existing form or report is that they (presumably) already function in the way that you want. The one possible downside is that they might only function properly because thay are part of the form or report. Of course, it is perfectly possible to create components that will only work when used in a specific environment, but as a general principle, it is better to make components as independant of their environment as possible.
A completely new component can be created in much the same way as a form or report. Go to the Components tab of the main database window, and double click on the Create new component item. This brings up a dialog similar to that which appears when you create a new form or report (except rather simpler). The important setting is the type, either Form component or Report component. Note that this cannot be changed once set.
Once through the initial properties dialog, objects (labels, fields, etc.) can be added to the component almost exactly as they can to a form or report. The most noticable difference is that a component never has an associated query. This means that if you add a data control, such as a field, then there are no table columns shown when you come to set the display expression. If you know that you will only use the component in a situation where (for instance) a column called user_name exists and is to be displayed, then you might set the display expression to user_name, but this rather limits the places you can use the component [60]. To help with this situation, however, you can make use of configuration properties.
When setting properties on objects, you may have noticed a property Configuration. This appears for all objects, but is mostly used in conjunction with components, where it provides a way of asking for and setting properties when the component is pasted. These are the settings that appear under the Configure tab of the component selection dialog. The screenshot below shows the properties dialog for the button which the stock first-record button provides, with the Configuration property selected. There is one configuration value, which provides the button text.
Normally, a configuration is associated with a property of the object, and the value in the configuration sets the value of the property when the component is pasted into a form or report. In the example above this provides the button text; the settings for this are:
Property | The property that this configuration value sets. | text is the property that specifies the text that the button displays. |
Legend | This is the text that appears under the Configure tab of the component selection dialog. | This should be set to some suitable prompt. |
Value | Default value to be used. | The default text for the first-record button is First. |
Type | Shows User, Required and Hidden settings; see below. | Shows U,R and/or H respectively. |
New configurations can be added by selecting a property, specifying a value and a legend, and clicking the Add button; configurations can be edited by clicking the Edit button (or by double- clicking the required entry), making changes and then clicking Add.
There are three additional settings for each configuration, User, Required and Hidden. When set, these show up as U, R and H in the Type column. If Required is set, then a value must be specified when the component is selected and pasted into a form or report. If Hidden is set, then then the configuration does not appear under the Configure tab of the component selection dialog. On its own, Hidden is not of much use, but is is useful in conjunction with the User setting, described below.
When the component is pasted into a form or report, the configuration values are used to set the corresponding properties. Then (unless User is set) the configuration values themselves are removed, and do not appear in the form or report definition.
The next screenshot shows the configuration settings for the stock search button. By default, the button initially shows the text Find. When clicked, the text changes to Go, and the user can enter search values into form fields (just as if the toolbar start-query button had been clicked). When clicked a second time, the query is executed and the button text returns to Find. To manage this, the component needs to incorporate two text values for the two button states.
In this example, the two configurations are both marked as User configurations. The immediate effect of this is that they are not removed when the component is pasted (so, if you paste the button into a form, and then look at the button properties, you will see that any User configurations are retained). Now, as they are retained in the form or report, they can be accessed by scripts. Getting a little ahead of ourselves (slots are described below), selecting the Slots property for this button, and then the blockAction slot, the dialog shown below would appear. In the script code, the bits like button.getConfig('text2') retrieve the configuration values (which are then used to set the button text).
Hence, in this example, the text configuration sets the initial button text, and then text and text2 are used as the query execution state switches back and forth.
Note that when User is set, the Property combobox is replaced by a text field, so that User configurations can be set to anything you like. In this example, the first is set to text since this is the property that sets the button text.
[57] Storing locally makes it easier to use the components in several Rekall databases, since they are accessible whatever Rekall database you have open. On the other hand, you could create a server database purely to hold components, and access it from all your Rekall databases.
[58] OK, three. Since components, like forms and reports, are defined in XML, they can be created using a text editor.
[59] This is one way to create a locally saved component.
[60] You could change the display expression when you paste the component into a form or report, but in that case you might as well leave it blank in the component.
Prev | Home | Next |
The Database Dumper and Loaders | Up | Advanced Scripting: Events and Slots |