This chapter contains the following topics:
The media object control is a specialized control. Use this control to enable the user to enter text or attach objects. You can place this control on any form type except the message box.
A single media object control can contain multiple items. Furthermore, depending on how it is configured, a media object can also contain a variety of different types of items. The user can only work with one at a time, however.
You can use the media object control in a variety of ways. You can add images, shortcuts to other applications, and text. You can add multiple media objects to a form. You can add multiple text objects to a single media object. You also can add generic files or URLs. If you want to display a file that is available on the internet, you can attach the media object control to the form and create a link to the internet.
After you define the media object queue for the internet and include a valid HTTP address, you can use the Start Web Browser system function to open the control and display the internet file. For example, you might use this control when you need to verify the Web page for a shipping vendor so that you can track the status of shipments. You can look up the shipment directly within the media object control.
You also can use the media object control to display the employee queues to which messages are sent. Place a media object control next to the tree control on a parent/child form. Next, use event rules (ER) to establish a relationship between the tree side and the media object side. For example, if a message is highlighted in the tree, then the corresponding message text appears in the control.
You can control the type of media objects users can attach by selecting one or more of these options:
Allow Image Items
Allow OLE Items
Allow RTF Text
Allow Text Items
Additionally, you can opt to cause a new text item to be created every time the control is opened by selecting the New Text Item on Open option.
Media object system functions enforce media object security in the web client. When applications that have media object security applied to them are running , the system logs the security information for the system functions in the web client debug log file.
This section discusses the system functions unique to media objects.
Use this system function to access a media object. Most of the media object system functions require you to use this system function to access a media object before you can manipulate it in another way.
Input, required. The media object FC to affect.
Input, required. The media object data structure to use. Set the parameter to an alphanumeric constant (<Literal>), a user prompt (<Choose GTName>), or an applicable object from the object list.
Input, required. The key string of the media object to access. Set the parameter to an alphanumeric constant (<Literal>), <Blank>, <Zero>, or an applicable object from the object list.
Input, required. The display mode for the media object. You can show the media object as a read-only object, or you can enable users to edit the media object. Set the parameter to <Edit> or <Display>.
Output, required. This parameter is reserved for future use.
Input, optional. The item to activate (that is, bring to the forefront of the control). A media object can have more than one item associated with it. If you want an item of a certain type to be displayed initially, specify it with this parameter. You can also choose to enable the user to select the initial display item type as well. Set the parameter to <First Image Item>, <First OLE Item>, <First Text Item>, or <Specify Item#>.
Use this system function to activate (that is, bring forward) a specific item in a given media object. You must first access the media object itself before activating its items.
Input, required. The media object FC to affect.
Input, required. The ID of the item to activate. Set the parameter to <First Image Item>, <First OLE Item>, <First Text Item>, or <Specify Item#>.Access Media Object
Use this system function to clear all values in the characterization cache that were set previously by the Set Characterization Cache system function. After this system function is called, adding media objects will not automatically generate a record in the F00166 table, which is where metadata about a media object is saved.
Input, required. The media object FC to affect.
Input, required. The media object data structure to clear. Set the parameter to an alphanumeric constant (<Literal>), a user prompt (<Choose GTName>), or an applicable object from the object list.Disable Characterization CacheSet Characterization Cache
Use this system function to delete a specified item from a given media object. You must first access the media object itself before deleting its items.
Input, required. The media object FC to affect.
Input, required. The ID of the item to delete. Set the parameter to <First Image Item>, <First OLE Item>, <First Text Item>, or <Specify Item#>.Access Media ObjectActivate Item
Use this system function to prevent runtime from changing the media object icon to represent the characterization of the media object.
Input, required. The media object FC to affect.
This system function accepts a media object item sequence number and an OLE automation server interface as parameters and returns a handle to the OLE object with that sequence number in the media object record.
Input, required. The media object FC to affect.
Input, required. The ID of the item containing the OLE object to be fetched. Set the parameter to <First Image Item>, <First OLE Item>, <First Text Item>, or <Specify Item#>.
Output, required. The object to which to return the ActiveX/COM interface variable. Set the parameter to an applicable object from the object list.
This system function returns the handle of the referenced OLE item to the object specified by ObjectRef. It also returns one of these two values:
Indicates that the system function succeeded.
Indicates that the system function failed.Insert OLE ObjectInsert URL
This system function adds an OLE object to a given media object.
Input, required. The media object FC to affect.
Output, required. The object to which to return the name of the item. Set the parameter to an alphanumeric constant (<Literal>), <Blank>, <Zero>, or an applicable object from the object list.
Input, required. The object to which to return the next available ID. Set the parameter to an alphanumeric constant (<Literal>) or <Null>.
Output, optional. Reserved for future functionality.
This system function returns the name of the inserted object, as well as the next available ID value to the objects indicated by Item Name and Item, respectively. It also returns one of these two values:
Indicates that the system function succeeded.
Indicates that the system function failed.Get OLE Item
Use this system function to add text object to a given media object.
Input, required. The media object FC to affect.
Input, required. The ID to assign to the item being inserted. Set the parameter to <Default Text Object> or an alphanumeric constant (<Literal>).
Input (EVDT_STRING ), required. The actual text to be inserted. Set the parameter to an alphanumeric constant (<Literal>), <Null>, or an applicable object from the object list.
Use this system function to place an HTML page in a media object. You must pass in the media object queue name where the HTML file resides and the name of the file.
Input, required. The media object FC to affect.
Input, required. The media object queue in which HTML files reside. Set the parameter to an alphanumeric constant (<Literal>), <Blank>, <Zero>, or an applicable object from the object list.
Input, required. The name of the HTML file to be attached. Set the parameter to an alphanumeric constant (<Literal>), <Blank>, <Zero>, or an applicable object from the object list.
This system function returns one of these two values:
Indicates that the system function succeeded.
Indicates that the system function failed.Get OLE ItemInsert OLE Object
This system function hides the viewer icon panel on a given media object control. When the panel is hidden, users cannot select particular media objects to view, although they can interact with any media object displayed in the main portion of the control. You can use the Activate Item system function to display different items in the media object programmatically.
Input, required. The media object FC to affect.
Input, required. Indicates whether to hide the icon panel. Set the parameter to <Yes> or <No>.
This system function exists for backwards compatibility. Do not use it.
Use this system function to set data in the characterization cache. This cache is saved in the F00166 table and is used as metadata.
Input, required. The media object FC to affect.
Input, required. The media object data structure to use. Set the parameter to an alphanumeric constant (<Literal>), a user prompt (<Choose GTName>), or an applicable object from the object list.
Input, required. The data values to use as metadata. Double-click <Define Characterization> to set the values.
This system function sets the cursor in a text type media object item either at the beginning of the text (Home position).
Note:
This system function has been marked for deprecation in a future release; therefore, avoid its use.Input, required. The media object FC to affect.
Input, required. The ID fo the text item that you want to affect. You can select a specific item, or you can choose to affect the default text item if you have configured the control at runtime so that a default text item launches each time the user opens the control. Set the parameter to <Default Text Object> or an alphanumeric constant (<Literal>).
Input, required. The position at which to place the cursor. Set the parameter to <HOME>.
Use this system function to determine whether a media object is associated with a given row record. If so, runtime can display a paperclip icon in its row header as a signal to the user that the media object exists.
Input, required. The grid FC to affect.
Input, required. The row to check. Set the parameter to an alphanumeric constant (<Literal>), <All Rows>, <Currently Selected Row>, or an applicable object from the object list.
Input, required. Indicates whether runtime should display the paperclip icon for the user if a media object is associated with the row. Set the parameter to <Yes> or <No>.
This system function enables you to set the text color for a text-type item in a given media object control.
Input, required. The media object FC to affect.
Input, required. The ID of the text item you want to affect. You can select a specific item, or you can choose to affect the default text item if you have configured the control at runtime so that a default text item launches each time the user opens the control. Set the parameter to <Default Text Object> or an alphanumeric constant (<Literal>).
Input, required. The color to be set. Set the parameter to a color from the color palette (<Pick Color>) or the default color value (<Reset Color>).