User Control definition file

Unofficial Content

This document will explain the structure of a User Control definition file (*.control) which is used to define the main characteristics of a User Control.

There are some configurations which cannot be modified using the User Control Editor and the file must be updated manually, this tags are:

  • Version: User Control version.
  • Actions: list of actions to apply when a dragging & dropping a User Control to a WebForm.
  • Categories: check detail below.
  • ResolverFactory: check detail below.
  • Methods: check detail below.
  • ControlType: check detail below.
  • SharedFile: check this article.

.control General structure :

<?xml version="1.0"?> 
<ControlDefinition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ControlDefinition> 
     <Version /> * Control version
         <Name /> * Control name
         <Description /> * Control description
         <Id /> * Internal identifier for the control
         <ObjClass /> * Internal name of the control
         <Constructor> * Control class constructor
                  <Name /> * Name

          <Parameters />* Parameters

</Constructor>

        <ControlType /> * Indicates if the control will be used as a Custom Grid. If value "grid" is set it is considered as a Custom Grid.

     <Categories > * Toolbox categories where the control will be placed.
          <Category />
           ...
     </Categories>

     <IncludeInControlInfo /> * Is the control included in the Control Info property?. (values can be true or false)
         <ToolboxIcon /> * Icon for use in GeneXus IDE toolbox
         <IsPublic /> * Indicates if the control will be available in the toolbox
     <SupportFiles> * Directories and files used by the control implementation
          <File /> * Files
           ...
          <Directory /> * Directories
           ...
     </SupportFiles> 
     <ReferencedFiles> * Referenced files by the control implementation (js, css). References to these files are included in the generated HTML.
          <File /> * Files
           ...
     </ReferencedFiles>
     <GxResources /> * XPZ file name with GeneXus resourses needed to use the control (SDTs, Domains, etc.)

     <RuntimeRender /> * Runtime render file name (javascript)
        <ShowMethod /> * Method of the runtime render file used for showing the control
         <ResizeSupported /> * Is resize supported for the control? (values can be true or false)

     <HeightPropertyName /> * Control height property name
     <WidthPropertyName /> * Control width property name
     <PropertiesDefinition /> * Control properties definition file name
         <ResolverFactory /> * Library (dll) which will handle the properties dynamism (i.e. hide properties when some values are selected)

     <DesignRender /> * Control design render file name
         <Html /> * Allows to define a basic render HTML with no need of modified xsl render file. If <DesignRender> is specified this tag has no effect.

     <Events> * User control events, implemented in the runtime render file
          <Event /> * Events
           ...
     </Events>
     <Methods> * User control methods 
          <Method>
               <Name /> * Method name
               <ReturnType /> * Type returned by the method
               <Parameters> * Methods parameters
                    <Parameter /> * Parameter type
                    ...
               </Parameters>
               <Signature /> * Method signature, used for the Intellisense          
          </Method>

     </Methods>
     <Actions>
                  // Actions to be executed when using the control (details below in this document)
     </Actions>
</ControlDefinition>

Actions structure:

<Action>
     <Order> * Execution order for the action. All actions will be executed following this order (minor number is executed first).
     <ActionProperties> * Action properties
          <Property>
               <Key> * Property key
                    <string /> * Key is specified inside this string tag
               </Key>
               <Value> * Property value
                    <string /> * Value is specified inside this string tag
               </Value>
          </Property>
     </ActionProperties>
     <Data /> * Data for action execution
     <ActionType /> * Action type (**)
</Action>

(**) Three types of actions can be specified on <ActionType> tag, (VarDeclaration, SetPropertyToControl and CodeSnippet), and the available values for the other tags depend on which type is being defined.

Var Declaration:

  • Variables properties have to be defined, for instance:
    • Key: Name, Value: <variableName>
    • Key: ATTCUSTOMTYPE, Value: <variableType>
    • Key: AttCollection, Value: true (if we want to set the variable as a collection)
  • <Data> tag has no effect

SetPropertyToControl:

  • Only one property is needed with Key: <controlPropertyName> and Value: <propertyValueToSet>, for each control property to be setted
  • <Data> tag has no effect

CodeSnippet:

  • Properties tags have no effect
  • <Data> tag value define the code to be added in the object events.

Some samples of the structure detailed above can be seen in the Hello World control definition file and the GXchart control definition file.

Categories

As of GeneXus X Evolution 1, you can define a category for your User Control, so it is listed in a separate section of the Toolbox. To define a category for a User Control you need to edit its .control file, find the following tag: <Categories />, and add your category as described in the example below.

<Categories>
     <Category>GXGoogle Visualization Library</Category>
</Categories>

Platforms

The Platforms tag needs to be included in the .control file. If the user control is going to be supported by the Abstract layout add this line:

<Platforms>
    <Platform>WebLayout</Platform>
  </Platforms>

Otherwise, if only the HTML Editor supports the UC, add

  <Platforms>
    <Platform>Web</Platform>
  <Platforms>

See Also

User control structure overview
HowTo : Define actions in the control definition file of a User Control