4D Objects

4D objects (C_OBJECT) are arguably the best addition to the 4D language in recent versions. They make programming much more natural and greatly simplify the coding of structures and data models.

Q2Pix uses 4D objects almost everywhere:

  • To pass containers of options to methods. This makes calling certain kinds of methods much more flexible than what is possible using fixed parameters.

    For example, the ImgFrame_CreateThumb method may accept a 4D object as an options parameter, through which the following can be defined:

    • The maximum size of the thumbnail.
    • Whether to fix the orientation of the thumbnail.
    • The format in which the thumbnail will be encoded.
    • Format-specific options:
      • Compression quality for lossy formats.
      • TIFF encoding scheme.

    All these options have default values, so callers can specify only the ones they want to customize, if any.

  • To return structured data as the result of method calls.

    For example, the ImgFormat_GetInfo method returns the characteristics of a supported image format as an object:

    • Name
    • MIMETypes
    • Extensions
    • CanEncode
    • IsRaster
    • IsVector
    • HasThumbnails
    • HasXMP

  • In plug-in area properties.

    The plug-in area exposes a set of named predefined properties such as the default zoom factor, and so on. It also allows developers to attach custom properties for their own use. These properties can be of simple types, such as strings and numbers, but they can as well be 4D objects

  • As configuration objects for the ImgControl subform, typically coming from JSON files stored in the “Resources” database folder.

  • As XMP namespace definitions in the generic XMP editor implemented in the Q2XMPLib component, coming from JSON files stored in component “Resources” folder.

Note

As of 4Dv16, there is no way for plug-ins to accept 4D objects as parameters or return 4D objects as result.

To overcome this limitation, Q2Pix plug-in methods use JSON text instead of 4D objects, while the Q2PixLib component provides handy wrappers that convert JSON text to/from 4D objects.

For example, the ImgFrame_GetGeometry component method is a wrapper to the ImgFrame_GetGeometry_JSN plug-in method, where the JSON result is converted to a 4D object. (Note the _JSN suffix in the plug-in method name.)

Common geometric objects

The structure of objects used in various places in Q2Pix varies per method or use, and is described in the corresponding section in the reference guide.

There are, however, three kinds of geometric objects that are commonly used as members of other objects or as method parameters and result: the SizeObj object, the PointObj object, and the RectObj object.

The SizeObj object

Describes a geometric size in a coordinate space:

Property Type Description
Width Real The size of the object on the X axis (horizontal size).
Height Real The size of the object on the Y axis (vertical size).

Example:

{
    "Width": 640,
    "Height": 480
}

The Q2PixLib component provides utility methods for creating and accessing members of SizeObj objects:

The PointObj object

Describes a point in a coordinate space:

Property Type Description
X Real The location of the point on the X axis.
Y Real The location of the point on the Y axis.

Example:

{
    "X": 100,
    "Y": 200
}

The Q2PixLib component provides utility methods for creating and accessing members of PointObj objects:

The RectObj object

Describes a rectangle in a coordinate space:

Property Type Description
X Real The location of the rectangle’s origin on the X axis.
Y Real The location of the rectangle’s origin on the Y axis.
Width Real The size of the rectangle on the X axis (horizontal size).
Height Real The size of the rectangle on the Y axis (vertical size).

Example:

{
    "X": 100,
    "Y": 200,
    "Width": 640,
    "Height": 480
}

The Q2PixLib component provides utility methods for creating and accessing members of RectObj objects: