Consultor Eletrônico

Ways to Modify an Attribute of a SmartObject Instance

INTRODUCTION
============
This knowledgebase entry discusses various ways to modify attributes
for a particular instance of a SmartObject. It specifically addresses
the various ways to create and use attributes with and without the
SmartObject's instance attribute dialog box. It also concentrates on
modifying the size of a SmartObject.

USER-DEFINED ATTRIBUTES
=======================
The simplest and most straightforward way to modify an attribute for
a SmartObject instance is with user-defined attributes. A
user-defined attribute can be created with set-attribute-list where
the instance of the SmartObject is being placed. That attribute can
then be used at runtime with get-attribute to set the SmartObjects's
attribute appropriately.

Modifying the size of a SmartViewer, as an example, includes the
following:

1) Size to fit in the SmartViewer's property sheet must be off.

2) The SmartViewer needs a local-initialize procedure which will run
get-attribute for the attribute and use the return-value to set the
attribute accordingly.

/* Code needs to be placed before the dispatch */
RUN get-attribute("SIZE").
IF RETURN-VALUE = "BIG" THEN ASSIGN
FRAME {&FRAME-NAME}:WIDTH-CHARS = 75
FRAME {&FRAME-NAME}:HEIGHT-CHARS = 15.

IF RETURN-VALUE = "SMALL" THEN ASSIGN
FRAME {&FRAME-NAME}:WIDTH-CHARS = 55
FRAME {&FRAME-NAME}:HEIGHT-CHARS = 4.

3) The SmartWindow in which the instance of the SmartViewer resides
needs a local-create-objects which will run set-attribute to set the
attribute for that particular instance.

/* Code needs to be placed after the dispatch */
RUN set-attribute-list IN h_V-CUST /* handle of the SmartViewer */
("SIZE = BIG").

The instance of the SmartViewer in any SmartWindow that sets the
size attribute to big will get a SmartViewer that is 75 by 15. Any
SmartWindow that sets it to small will get a SmartViewer that is
55 by 4. If it is not set at all, the instance will inherit the size
from its master.

Whether a particular SmartObject's attribute can be modified for an
instance of the SmartObject depends on the SmartObject being used and
if the attribute can be set dynamically or not. For example, browses
cannot be resized dynamically so the above could not be applied to a
SmartBrowser.

MODIFYING INSTANCE ATTRIBUTE DIALOG BOXES
=========================================
Another way to modify an attribute for the instance of a SmartObject
is to add the attribute to an existing Instance Attribute Dialog Box
or to create an Instance Attribute Dialog Box for the master
SmartObject. This is beneficial if an attribute is likely to be
changed for every instance of the SmartObject.

For example, if it was necessary to change the background and
foreground colors of each instance of a particular SmartBrowser
master, the following could be done:

1) A copy of DLC\src\adm\support\browserd.w should be copied to the
working directory. This is the PROGRESS-supplied instance attribute
dialog box for a SmartBrowser.

2) This program would need the following modifications:

a) Integers fi_BGC (background color) and fi_FGC (foreground) need to
be added to the interface of the dialog box

b) The following needs to be added to the main block of code before
the RUN enable_UI:

RUN get-attribute IN p-Parent-hdl('BGCOLOR').
fi_BGC = INTEGER(RETURN-VALUE).
RUN get-attribute IN p-Parent-hdl('FGCOLOR').
fi_FGC = INTEGER(RETURN-VALUE).

c) The new integer fields, fi_BGC and fi_FGC, need to be added to the
ASSIGN statement in the main block of code.

d) The attr-list assignment needs to be modified to include the new
attributes, BGCOLOR and FGCOLOR:

attr-list = "BGCOLOR = ":U + STRING(fi_BGC) +
",FGCOLOR = ":U + STRING(fi_FGC) +
",DISABLE-ON-INIT = ":U + STRING(V-Disable) + etc...

e) If you want the new attributes to be visualized in the instance of
the SmartObject, the following can be added to the main block of code
after the RUN set-attribute-list:

RUN dispatch in p-Parent-hdl ('initialize':U).

3) Create a new Method Library as per kbase 15815, and copy
DLC\src\adm\method\browser.i into the new library.

4) Modify the definition of the preprocessor adm-attribute-list in the
new browser.i to include the additional instance attributes:

&SCOP adm-attribute-list FGCOLOR,BGCOLOR,Initial-Lock,...etc.

5) The SmartBrowser master needs a local-initalize procedure to run
get-attribute to get the new attributes that have been created and set
with the Instance Attribute Dialog Box. It needs to then take the
value of those attributes to set the frame colors accordingly:

/* Code needs to be place before the dispatch */
RUN get-attribute('BGCOLOR':U).
ASSIGN FRAME {&FRAME-NAME}:BGCOLOR = INTEGER(RETURN-VALUE)
NO-ERROR.
RUN get-attribute('FGCOLOR':U).
ASSIGN FRAME {&FRAME-NAME}:FGCOLOR = INTEGER(RETURN-VALUE)
NO-ERROR.

Note that using an Instance Attribute Dialog Box is essentially using
user-defined attributes as described in the USER-DEFINED ATTRIBUTES
section. But it provides a generic and easy way of changing an
attribute for each instance of a SmartObject master. It also enables
the programmer assembling SmartObjects into a SmartContainer a way to
have the set-attribute coding done for them instead of creating a
local-create-objects procedure.

SPECIFIC SMARTOBJECT SIZING OPTION
==================================
Specific to resizing a SmartObject, is an option of adding a
"set-size" method procedure to the SmartObject. If a SmartObject
contains such a method (such as the SmartFolder and SmartPanel do), it
will be resizable in the UIB when an instance of it is placed in a
SmartWindow. It will have handles which will allow the user to
physically resize it. The SmartFolder (src\adm\objects\folder.w) and
SmartPanel (src\adm\methods\panelsiz.i) "set-size" methods can be used
as examples for writing such methods for other SmartObjects.
dynamically.

REFERENCES TO WRITTEN DOCUMENTATION
===================================
PROGRESS User Interface Builder Developer's Guide
Using the PROGRESS Application Component Environment (ACE)

Progress Software Technical Support Note # 15476