Content definition
Content or concept documentation describes the data shown in the control or the concept of an action or other GUI element. Content description is optional, but helpful in many cases.
- Defining short help text for GUI elements ( Tool Tip )
- Content description to be displayed when requesting more help by pressing Ctrl+Shift+F1 ( Content help )
The Label defined for the content description is only used for initializing usage hints. The Title from the content definition is shown as tool tip, when no tool tips have been defined in user hints definitions ( User Hints ). The characteristic will be displayed as content help. When the field is empty, hints from Text definitions are shown when requesting content help.
In order to edit content documentation, the Description tab on bottom of the Text Definitions form has to be activated, which is provided in GUI resource forms that support content definitions.
Text definitions for fields are initialized, when fields have been dragged into the form or when adding a field to a form with the name of a property of the current class. When being initialized from property data source definition, the content definition shares the documentation topic with the property documentation. One may duplicate, remove or re-associate a topic definition by changing the topic number right of the language field (see Topic number below).
void ADK_Class::SetupContentDocu() {
VARIABLES
set<ADK_Field> &field = controls.fields;
PROCESS
top;
while ( next )
while ( controls.next )
while ( field.next )
field.instanceAction("UpdateContentTopic"); // replaces also existing topics
}
In order to update existing field definitions, the instance action UpdateContentTopic() might be called for all field resources (see example). The action will automatically link content definitions to the field definitions, when no content definition has been defined so far and when the field refers to a property data source, which provides documentation.
The language for description topics can be selected from the drop list. The default language is the language activated in the Designer's Options/Language menu. Changing the language allows entering the text in alternative languages.
The label defined in the content definition is used for initializing the user hint title when creating the GUI resource object. Any modification of the field later on will not affect the label definition in user hints.
The title defined for the content description is used as user hint tool tip, as long as no tool tip has been defined in user hint text definitions. The content title becomes visible again, when removing all text from the tool tip definition in user hint text settings.
The characteristic field contains detailed content or concept description. For controls referring to class properties this is often the property definition of the data source in the database, i.e. the content definition from the property might be reused here. For actions and buttons, the function or process definition of the action to be executed might be linked to the control as content definition.
Content topics are common resources which might be linked with different development resources. Typically, data controls (ADK_Field) are linked with the definition topic linked to the property definition in a complex data type.
When documentation topics are shared with other resources, this is indicated by red topic number right of the language field. When the documentation topic is used exclusively by the GUI resource, the topic number is displayed green.
Documentation topics might be updated, localized, linked or re-associated.
- New - When no content documentation has yet been associated with the GUI resource (fields are disabled or topic number is 0 ) , a new topic might be created by clicking "Create new content topic" button. Now, a green number appears in the topic number area and text might be entered.
- Link - in order to link a topic to the content documentation, one may look for the proper definition topic in Terminus and input the topic number of this topic in the topic number field. When leaving the field, the topic text will be displayed and the topic number is displayed in red color.
- Remove - In order to remove the link to the associated content topic, the topic number field has to be cleared.
- Update - Updating is simply done by entering the text as required. When the topic is shared with other resources, this will change the documentation of those resources, too.
- Localize - in order to create an exclusively used topic from a shared one, the "Create new content topic" button may be clicked. In this case, the current documentation will be copied to the new topic created. The new topic number appears in the topic number field with green figures.
- (Re)associate - when the data source has been changed or for several other reasons it might be necessary, to (re)associate the topic with data source documentation. By pressing the "Associate content topic" button the system looks for a data source documentation topic. When being found, it will be linked to the content documentation and the topic number will be displayed in the topic number field (red). The topic previously linked with the content documentation will be removed. When no data source documentation could be detected, the content documentation remains unchanged.