User Objects

User objects

Important Requirements

  • For standard class user objects:

    1. Standard class user objects can only inherit from the following non-visual system objects: DataStore, Transaction Object, DynamicStagingArea and OLEObject.

    2. Non-visual standard class user objects must be defined in a PowerBuilder painter. They can be dynamically created (for example, by using the CREATE statement).

    3. If a non-visual object is a local variable, the Destructor event in the non-visual object cannot be triggered unless there is a Destroy statement for the non-visual object as well.

  • For custom class user objects:

    1. Non-visual custom class user objects must be defined in PowerBuilder painter. They can be dynamically created (for example, by using the CREATE statement).

    2. If a non-visual object is a local variable, the Destructor event in the non-visual object cannot be triggered unless there is a Destroy statement for the non-visual object as well.

  • For standard and custom visual user objects:

    1. Must be defined in PowerBuilder painter.

    2. The SetFocus function is not supported for custom visual user objects, but is supported for standard visual user objects.

    3. Standard Visual Object is an extension of the visual system object (control), and it is used to customize the function of the visual system object (control). For more details, please refer to System Objects and Controls.

Supported

  • Custom class user objects

  • Custom visual user objects

  • Standard class user objects

  • Standard visual user objects

Unsupported

  1. External visual user objects

    In the PowerBuilder application, the Destructor event sequence for a user object will be triggered in accordance with the Control[] property of the user object. In the mobile application, the Destructor event sequence is unsupported.

  2. Nonvisual objects (Custom Class Objects and Standard Class Objects)

    To insert nonvisual object(s) between objects (window, user object, NVO, application), you can select any items on the Insert | Object menu of the PowerBuilder painter. However, PowerServer does not support this.

Autoinstantiated NVO

  • Declaring an autoinstantiated NVO

    1. Declaring an autoinstantiated user object creates an instance of that object (just like a structure), and the Constructor events are triggered for the instance variables.

    2. If an instance variable contains an autoinstantiated NVO(b) and the Constructor event is triggered for the instance variable, an instance of NVO(b) is automatically created, and the Constructor events are triggered for the instance variables of NVO(b).

  • Assignment for autoinstantiated NVO

    1. When an autoinstantiated object is assigned to another autoinstantiated object, the whole object is copied to the second variable.

      For example:

      n_cst_string lnv_string1, lnv_string2
      lnv_string2 = lnv_string1      //lnv_string2 is a copy of 
      lnv_string 1
      
    2. Assigning a NonVisualObject object to an autoinstantiated NVO or a NonVisualObject object is unsupported. Note that NonVisualObject is a system object and it is different from an NVO (non visual user object).

      For example, the following script is unsupported:

      NonVisualObject lnv_test   //lnv_test is a NonVisualObject object
      n_cst_string lnv_string   //n_cst_string is an autoinstantiated NVO
      lnv_test = lnv_string //unsupported
      

  • Defining autoinstantiated NVO

    The following can be included in the definition of an autoinstantiated NVO:

    1. Instance variable. The instance variable can be an autoinstantiated NVO, an object, or have the same name as a window instance variable.

    2. System function or user defined function or object function.

    3. Constructor event, or object event or user-defined event.

    4. Using a Destructor event in the definition of an autoinstantiated NVO is unsupported.

  • Autoinstantiated NVO array

    1. If the autoinstantiated NVO array is a fixed-size array and the array is declared, instances of each NVO are created, the instance variables of each NVO are instantiated, and the Constructor event is triggered for each instance variable.

      For example:

      n_cst_string lnv_string[10]
    2. If the autoinstantiated NVO array is variable-size array, the NVO instances are not created when the array is declared. When an array element is named (an NVO), the instances of the element and the foregoing elements are created, the instance variables of each NVO are instantiated, and the Constructor event is triggered for each instance variable.

      For example:

      n_cst_string lnv_string[]
      lnv_string[10].is_source = ls_model
      
  • Autoinstantiated NVO as a structure member

    When the structure is declared, an instance of the autoinstantiated NVO is created. When the structure is called, the Constructor event is not triggered for the NVO. In PowerBuilder, the Constructor event is triggered when the NVO is first used.

  • Inheritance

    Inheritance is supported if the ancestor of an autoinstantiated NVO is a nonautoinstantiated NVO.

Nonautoinstantiated NVO

  • Declaring a non-autoinstantiated NVO

    1. To use a non-autoinstantiated NVO, you will have to declare a variable of the user object type and create an instance of it using the CREATE statement. Declaring an object variable declares an object reference.

      For example:

      n_base lnv_base     //n_base is a nonautoinstantiated NVO
      lnv_base = Create n_base    //Create an instance of n_base

      Note: PowerBuilder also supports using a non-autoinstantiated NVO by directly placing the non-autoinstantiated NVO in a window or user object (using the Insert menu or the drag-and-drop technique so it can be listed in Non-Visual Object List view), however, the instance created by this method is unsupported by PowerServer.

    2. When the object instance is created, the instance variables of the NVO are instantiated, and the Constructor event is triggered for each instance variable.

    3. Instantiating an ancestor variable with an instance of one of its descendants is supported.

      For example:

      n_base lnv_base   //n_base is a nonautoinstantiated NVO
      lnv_base = Create using "n_cst_sqlspy" //n_cst_sqlspy is a descendant of n_base
  • Assignment for nonautoinstantiated NVO

    1. When a non-autoinstantiated object is assigned to another non-autoinstantiated object, a reference to the object instance is copied. Only one copy of the object exists.

      For example:

      n_cst_string lnv_string1, lnv_string2
      lnv_string2 = lnv_string1  //Both point to same object instance
    2. Unlike autoinstantiated NVOs, assigning a NonVisualObject object to a non-autoinstantiated NVO or assign a non-autoinstantiated NVO to a NonVisualObject object is supported.

      For example, the following script is supported:

      NonVisualObject lnv_test //lnv_test is a NonVisualObject object
      n_cst_string lnv_string2 //n_cst_string is a non-autoinstantiated NVO
      lnv_test = lnv_string2   //supported
  • Defining non-autoinstantiated NVOs

    The following can be included in the definition of a non-autoinstantiated NVO:

    1. Instance variables. An instance variable can be an autoinstantiated NVO, an object, or have the same name as a window instance variable.

    2. System, user defined, or object functions.

    3. Constructor, Destructor, object, and user-defined events. The Destructor event cannot be triggered unless there is a Destroy statement for the object as well.

  • Non-autoinstantiated NVO array

    There can be fixed-size or variable size non-autoinstantiated NVO arrays. When the array is declared, an instance of the object is not created. A non-autoinstantiated NVO will only be created when there is a CREATE statement for the NVO.

  • Non-autoinstantiated NVO as a structure member

    1. Defining a non-autoinstantiated NVO in a structure is supported.

      For example:

      global type str_model from structure
      string s_emplid
      Date ld_inputday
      n_cst_base lnv_base
      end type
    2. When the structure is declared, an instance of the non-autoinstantiated NVO is not created. A non-autoinstantiated NVO will only be created when there is a CREATE statement for the NVO.