Control Add Graphic

[Gary Beene]

Please add your comments and suggestions as a Reply to this thread.





PB/WIN - CONTROL ADD GRAPHIC statement

Purpose

Add a static graphic control to a dialog for drawing, pictures, text, etc.

Syntax

CONTROL ADD GRAPHIC, hDlg, ID, Txt$, x, y, nWide, nHigh [,style] [,exstyle] [,CALL CallBack]

hDlg

Handle of the dialog in which the graphic control will be placed. The dialog will become the parent of the control.

ID

A unique numeric identifier for this control which is specified by the programmer. It must be an integral value in the range of 1 to 65535. This ID is usually specified with a numeric equate for clarity of the code. For example, the equate %IDC_GRAPHIC1 is more informative than a literal value such as 497. PowerBASIC recommends that identifier values should start at 100 to avoid conflict with any of the standard predefined identifiers.

Txt$

Text to associate with the Graphic control. A Graphic control does not display this text, so it is common to set this value to a null, empty string literal ("" or $NUL).

x, y

Integral expressions which specify the location of the control within the dialog client area. X is the horizontal position, and Y is the vertical position. 0,0 refers to the upper left corner of the Dialog. Coordinates are specified in the same terms (pixels or dialog units) as the parent dialog.

nWide, nHigh

Integral expressions which specify the overall width and height of the image area. If you choose a style which includes a border, the client area will be slightly smaller, in order to accommodate it. You use GRAPHIC GET CLIENT to determine the exact client size available to you. The width and height are given in the same terms (pixels or dialog units) as the parent dialog.

style

Optional primary style of the image control. This value can be a combination of the values below, combined together with the OR operator to form a bitmask. If style is omitted, the default combination is %WS_CHILD OR %WS_VISIBLE OR %SS_OWNERDRAW.

%SS_NOTIFY

Send %STN_CLICKED and %STN_DBLCLK notification messages to the Callback Function when the user clicks or double-clicks the control.

%SS_SUNKEN

Draw a half-sunken border around the graphic control.

%WS_BORDER

Add a thin line border around the graphic control.

%WS_DLGFRAME

Create a graphic control that has a border of the style typically used with dialog boxes.

exstyle

Optional extended style of the graphic control. This value can be a combination of the values below, combined together with the OR operator to form a bitmask. If exstyle is omitted, there is no default extended style.

%WS_EX_CLIENTEDGE

Apply a sunken edge border to the control.

%WS_EX_STATICEDGE

Apply a three-dimensional border style to the control (intended to be used for items that do not accept user input).

callback

Optional name of a Callback Function that receives all %WM_COMMAND and %WM_NOTIFY messages for the control. See the #MESSAGES metastatement to choose which messages will be received. If a callback for the control is not designated, you must create a dialog Callback Function to process messages from your control.

If the Callback Function processes a message, it should return TRUE (non-zero) to prevent the message being passed unnecessarily to the dialog callback (if one exists). The dialog callback should also return TRUE if the notification message is processed by that Callback Function. Otherwise, the DDT engine processes unhandled messages.

Remarks

A graphic control is typically used with graphic statements to draw graphs, pictures, text, etc. After you create a graphic control, you would normally use GRAPHIC ATTACH to select it as the target of subsequent GRAPHIC statements. However, if there is no selected graphic target at the time of creation, the new Graphic Control is automatically attached and selected.

A graphic control will only send notification messages to a callback if the %SS_NOTIFY style is used. Notification messages are sent to the callback function with CB.MSG = %WM_COMMAND, CB.CTL holding the ID (id&) of the control, and CB.CTLMSG holding one of the following values:

%STN_CLICKED

Sent when the user clicks a mouse button on the graphic control (unless the image control has been disabled).

%STN_DBLCLK

Sent when the user double-clicks on a graphic control (unless the control has been disabled).

%STN_DISABLE

Sent when a graphic control has been disabled.

%STN_ENABLE

Sent when a graphic control has been enabled.

When a callback function receives a %WM_COMMAND message, it should explicitly test the value of CB.CTL and CB.CTLMSG to guarantee it is responding appropriately to the notification message.

All PowerBASIC graphical displays are persistent -- they will be automatically redrawn when altered or temporarily covered by another window.

See Also

Dynamic Dialog Tools, GRAPHIC ATTACH, GRAPHIC COLOR, GRAPHIC SCALE, GRAPHIC SET FONT, GRAPHIC STYLE, GRAPHIC WIDTH, GRAPHIC WINDOW

[Michael Boho]

The GRAPHIC control is a great control, but it's characteristics need to be revised so it doesn't "eat" keystrokes, especially the TAB, as the default.

I suspect it's a specialized version of "static" control class, same as the LABEL control. I would like it to behave more like a LABEL with the ability to respond to mouse movements and actions if the %NOTIFY is enabled similar to the LABEL control.

I suspect implementing this could be difficult with all the GRAPHIC commands for equivalent API graphical implementations.

[Ross Boyd]

The GRAPHIC control is a great control, but it's characteristics need to be revised so it doesn't "eat" keystrokes, especially the TAB, as the default.

Yep, this is a bug but there's a simple workaround.

The control mistakenly defines %ws_tabstop as one of its default style attributes. The workaround is to explicitly define the style (without using %ws_tabstop) and the keystroke issue goes away.

The next beta release should resolve the problem.

[Rodney Hicks]

Michael, Ross,

Can either of you post a bit of compilable code showing what you mean. I don't know exactly how you are experiencing this phenomena. Especially as a comparison to the LABEL.

I can't tell if this is a documentation issue or a New Feature Suggestion from this discussion so far, if the latter, it should be in a different thread.

[Michael Boho]

Rodney,
Although the default style of the graphic control is supposed to be %WS_CHILD OR %WS_VISIBLE OR %SS_OWNERDRAW, this is incorrect.
Instead, it's %WS_CHILD OR %WS_VISIBLE OR %SS_OWNERDRAW OR %WS_TABSTOP.
As a result, you get an unanticipated tabstop added to the control.
Because you can change the default behavior by "rolling you own" style choices, I use,
CONTROL ADD GRAPHIC, hDlg, cID, "", XPos, YPos, Width, Height, %WS_CHILD OR %WS_VISIBLE OR %SS_OWNERDRAW AND NOT %WS_TABSTOP
Although it's not necessary, I add the AND NOT %WS_TABSTOP just to be sure.
CONTROL ADD GRAPHIC, hDlg, cID, "", XPos, YPos, Width, Height, %WS_CHILD OR %WS_VISIBLE OR %SS_OWNERDRAW also works.

[Michael Boho]

Here's what I mean:

#COMPILE EXE  'PBWin 10.04
#DIM ALL
GLOBAL hDlg AS DWORD

FUNCTION PBMAIN () AS LONG
  DIALOG NEW PIXELS, 0, "Where's the rollover focus?", , , 300, 200, %WS_POPUPWINDOW OR %WS_CAPTION TO hDlg
  CONTROL ADD TEXTBOX, hDlg, 100, "Line 1", 100, 30, 100, 22
  CONTROL ADD TEXTBOX, hDlg, 101, "Line 2", 100, 80, 100, 22
  CONTROL ADD TEXTBOX, hDlg, 102, "Line 3", 100, 130, 100, 22
  'this causes the problem
  CONTROL ADD GRAPHIC, hDlg, 103, "", 0, 0, 10, 10
  'this fixes the problem
  'CONTROL ADD GRAPHIC, hDlg, 103, "", 0, 0, 10, 10, %WS_CHILD OR %WS_VISIBLE OR %SS_OWNERDRAW
  DIALOG SHOW MODAL hDlg, CALL DlgProc
END FUNCTION

CALLBACK FUNCTION DlgProc AS LONG
END FUNCTION

[Michael Mattias]

%MY_DEFAULT_GRAPHIC_STYLE= %WS_CHILD OR %WS_VISIBLE _ 
       OR %SS_OWNERDRAW AND (NOT %WS_TABSTOP) 

CONTROL ADD GRAPHIC, hDlg, cID, "", XPos, YPos, Width, Height, _
           %MY_DEFAULT_GRAPHIC_STYLE

Easier to change your mind. Also to see what you have done. Also to not forget that the current documentation is inaccurate. Also less typing on each CONTROL ADD GRAPHIC statement.

[Michael Boho]

Don't need to add the parentheses around "NOT %WS_TABSTOP".

Minus style points.

[Michael Mattias]

NO, that is PLUS style points.

It adds clarity to the source code (maintenance +), is easier to modify since you only have to make the change in one place (maintenance +) , and since the evaluation is done at compile time, it costs zero at run time (performance wash). A wash and two plusses add up to a plus.

[Michael Boho]

Correction to my post:
Use of equate = + style points if more than one control uses it
Use of needless parentheses in boolean expression = - style points
Net = wash

[Kurt Kuzba]

I've noticed that none of the CONTROL ADD help files include
%SS_OWNERDRAW as one of their styles. Even ADD CONTROL GRAPHIC
omits it, even though it is given as part of the default style.

[Michael Mattias]

I've noticed that none of the CONTROL ADD help files include
%SS_OWNERDRAW as one of their styles.Even ADD CONTROL GRAPHIC
omits it, even though it is given as part of the default style.

And? Maybe that style is omitted from the supported styles because the DDT engine is assuming all responsibility for painting the control.. especially the GRAPHICS control, which the programmer paints using other GRAPHICS statements.

Come to think of it, that style is not so much "omitted" as it is "not supported."

You have to remember, the CONTROL ADD GRAPHICS statement adds a proprietary control to your DDT-managed screen.... it is dangerous to assume that control does anything not documented. "How" a proprietary control is implemented is subject to change without notice; the publisher's only responsibility is to ensure all documented statements which operate on that control "work as advertised."

If you want to owner-draw any control and still stay within the DDT rules, all you have to do is..

  CONTROL ADD "button" ....     %WS_CHILD OR %SS_OWNERDRAW

.. instead of using ...

  CONTROL ADD BUTTON  .... [, Styles]

Now you can use the CONTROL SEND statement to manipulate the control using the messages documented by the control publisher (Microsoft) in the control documentation.


MCM