ObjectWindows Library Help Contents

Click the icon above to open all folders. Click an icon below to open a folder or click the underlined text to see a specific topic.

Welcome to Help for the Borland C++ ObjectWindows Library.

	What's New in ObjectWindows 2.5?
	Tasks topics describing how to use ObjectWindows.
	Language Reference for ObjectWindows classes, including constants, types, macros, and enums.
Shortcut: 	Use the Search button at the top of the Help window if you are ready to look for something by name.


Contents: Essentials
ObjectWindows Library Help Contents

Click the icon above to open all folders. Click an icon below to open or close a folder. Click the underlined text to see a specific topic.

Welcome to Help for the Borland C++ ObjectWindows Library.

	What's New in ObjectWindows 2.5? Inheritance diagrams in ObjectWindows Help Complete encapsulation of OLE 2 using ObjectComponents New factory templates to support OLE New data type definitions 32-bit programs can use VBX controls
	Tasks topics describing how to use ObjectWindows.
	Language Reference for ObjectWindows classes, including constants, types, macros, and enums.
Shortcut: 	Use the Search button at the top of the Help window if you are ready to look for something by name.


Contents: Tasks
ObjectWindows Library Help Contents

Click the icon above to open all folders. Click an icon below to open or close a folder. Click the underlined text to see a specific topic.

Welcome to Help for the Borland C++ ObjectWindows Library.

	What's New in ObjectWindows 2.5?
	Tasks topics describing how to use ObjectWindows. Application and Module Objects Overview Command Enabling Control Objects Dialog Box Objects DLL Functions Doc/View Objects Event Handling Exception Handling Gadget Objects Graphics Objects Interface Objects Menu Objects OLE: ObjectComponents Framework (OCF) Tasks Printer Objects Validator Objects Visual Basic Control Objects Window Objects
	Language Reference for ObjectWindows classes, including constants, types, macros, and enums.
Shortcut: 	Use the Search button at the top of the Help window if you are ready to look for something by name.


Contents: Reference
ObjectWindows Library Help Contents

Click the icon above to open all folders. Click an icon below to open or close a folder. Click the underlined text to see a specific topic.

Welcome to Help for the Borland C++ ObjectWindows Library.

	What's New in ObjectWindows 2.5?
	Tasks topics describing how to use ObjectWindows.
	Language Reference for ObjectWindows classes, including constants, types, macros, and enums. ObjectWindows Library Classes ObjectWindows Library Constants ObjectWindows Library Enumerated Types ObjectWindows Event Handlers ObjectWindows Library Functions ObjectWindows Library Hierarchy Diagram ObjectWindows Library Macros ObjectWindows Library Type Definitions OLE: ObjectComponents Framework (OCF) Reference
Shortcut: 	Use the Search button at the top of the Help window if you are ready to look for something by name.


ObjectWindows Library Help Contents (all folders open)
ObjectWindows Library Help Contents

Click any icon to close all folders or click the underlined text to see a specific topic.

Welcome to Help for the Borland C++ ObjectWindows Library.

	What's New in ObjectWindows 2.5? Inheritance diagrams in ObjectWindows Help Complete encapsulation of OLE 2 using ObjectComponents New factory templates to support OLE New data type definitions 32-bit programs can use VBX controls
	Tasks topics describing how to use ObjectWindows. Application and Module Objects Overview Command Enabling Control Objects Dialog Box Objects DLL Functions Doc/View Objects Event Handling Exception Handling Gadget Objects Graphics Objects Interface Objects Menu Objects OLE: ObjectComponents Framework (OCF) Tasks Printer Objects Validator Objects Visual Basic Control Objects Window Objects
	Language Reference for ObjectWindows classes, including constants, types, macros, and enums. ObjectWindows Library Classes ObjectWindows Library Constants ObjectWindows Library Enums ObjectWindows Event Handlers ObjectWindows Library Functions ObjectWindows Library Hierarchy Diagram ObjectWindows Library Macros ObjectWindows Library Type Definitions OLE: ObjectComponents Framework (OCF) Reference
Shortcut: 	Use the Search button at the top of the Help window if you are ready to look for something by name.


Essentials
What's New in ObjectWindows 2.5?

ObjectWindows 2.5 provides several new features that make it easier for you to design applications that run faster, write code that is easier to debug, and create programs that implement linking and embedding technology. See the OWLDOC.WRI and the README files for more details on these and other new features.

ObjectWindows Help provides new inheritance diagrams a class's parent class and any child classes.

ObjectWindows 2.5 provides the following enhancements over version 2.0:

Complete encapsulation of OLE 2 using ObjectComponents

New factory templates to support OLE

New data type definitions

32-bit programs can use VBX controls


OWLInheritanceDiagramsinObjectWindowsHelp
Inheritance Diagrams in ObjectWindows Help

Inheritance

ObjectWindows Help provides new inheritance diagrams for each class that show the class's parent class and any child classes. Classes that have neither a parent nor a child do not have inheritance diagrams.

To access the inheritance diagram for a class, display the Help topic for the class, then click the Inheritance jump just under the heading. This topic has a sample Inheritance jump (for the TWindow class).


New Data Type Definitions

ObjectWindows data types have been updated to use more portable type names. The following table lists the Windows API type names, the underlying C type definitions used by Windows, and the new ObjectWindows type names.

Windows 	C definition	New type	Description

char	int8	Used when 8 bit signed value is needed.

BYTE 	unsigned char	uint8	Always 8 bits

WORD	unsigned short	uint16	Always 16 bits

int  	int	int	16 or 32 bits depending on platform

UINT 	unsigned int	uint	16 or 32 bits depending on platform

LONG  	long	long, int32	Could be 64 bits on some platforms

ULONG	unsigned long	ulong, uint32	Could be 64 bits on some platforms

long	int32	Always 32 bits

DWORD	unsigned long	uint32	Always 32 bits

BOOL	int	bool	New C++ type if available; otherwise an enum

TRUE     	1	true

FALSE    	0	false

The new C++ type, which maps a nonzero value to true, lets you assign an integer to a bool. You can then compare this Boolean value to true.


Language Reference: By Category
Language Reference

ObjectWindows Library

ObjectWindows Library Classes

ObjectWindows Library Constants

ObjectWindows Library Enumerated Types

ObjectWindows Event Handlers

ObjectWindows Library Functions

ObjectWindows Library Hierarchy Diagram

ObjectWindows Library Macros

ObjectWindows Library Type Definitions

OLE: ObjectComponents Framework Reference

Shortcut: 	Use the Search button at the top of this Help window if you are ready to look for something by name.


Tasks

Application and Module Objects Overview

Command Enabling

Control Objects

Dialog Box Objects

DLL Functions

Doc/View Objects

Event Handling

Exception Handling

Gadget Objects

Graphics Objects

Interface Objects

Menu Objects

OLE: ObjectComponents Framework (OCF) Tasks

Printer Objects

Validator Objects

Visual Basic Control Objects

Window Objects


Application Objects
Application and Module Objects

Application and Module Objects Overview

Application Message Handling

Closing Applications

Initializing Applications

Using Control Libraries


Command Enabling

Command Enabling Overview

Handling Command-Enabling Messages

Enabling and Disabling Command Items

Changing Menu Item Text

Toggling Command Items


Control Objects

Control Objects Overview

Control Classes

What Are Control Objects?

Constructing and Destroying Control Objects

Communicating with Control Objects

Using Particular Controls

Setting and Reading Control Values


Dialog Box Objects

Associating interface objects with controls

Dialog Box Objects Overview

Manipulating controls in dialog boxes

Using a dialog box as your main window

Using common dialog boxes

Using dialog box objects


DLL Functions

DLL Entry and Exit Functions (ObjectWindows)

Exporting DLL Functions (ObjectWindows)

Implicit and Explicit Loading (ObjectWindows)

Importing (calling) DLL Functions (ObjectWindows)

Mixing Static and Dynamic-linked Libraries (ObjectWindows)

Using ObjectWindows as a DLL (ObjectWindows)

Writing DLL Functions Overview

Writing Shared Classes (ObjectWindows)


Doc/View Objects

Doc/View Objects Overview

Creating a Document Class

Creating a View Class

Doc/View Event Handling

Doc/View Properties

Document Templates

How Documents and Views Work Together

Using the Document Manager


Event Handling

Event Handling Overview

Declaring Response Tables

Defining Response Tables

Defining Response Table Entries


Exception Handling

ObjectWindows Exception Handling

ObjectWindows Exception Hierarchy

Working with TXBase

Working with TXOwl

Specialized ObjectWindows Exception Classes

ObjectWindows Exception-Handling Macros


Gadget Objects

Class TGadget

Gadget Windows

Class TBitmapGadget

Class TButtonGadget

Class TControlGadget

Class TSeparatorGadget

Class TTextGadget


Graphics Objects

Changes To Encapsulated GDI Functions

GDI Class Organization

Graphics Objects Overview

TBitmap Class

TBrush Class

TCursor Class

TDib Class

TFont Class

TIcon Class

TPalette Class

TPen Class

TRegion Class

Working with Device Contexts


Interface Objects

Interface Objects Overview

Creating Interface Objects

Destroying Interface Objects

Parent and Child Interface Elements

Registering Window Classes

The Generic Interface Object: TWindow


Menu Objects

Constructing Menu Objects Overview

Modifying Menu Objects

Querying Menu Objects

Using Menu Objects With Frame Windows

Using Popup Menu Objects

Using System Menu Objects


OLE Support

For reference and task-oriented information on ObjectComponents Framework classes,
click the OCF button on the button bar.

Several new OLE-related classes have been added to the ObjectWindows API, among them, TLocaleString, TOleClientDC, TOleDocument, TOleFrame, TOleMDIFrame, TOleView, and TOleWindow.

ObjectComponents Framework (OCF) for 16-bit OLE support

ObjectWindows includes a new set of classes for making programs that support the following OLE capabilities:

Linking and embedding containers

Linking and embedding servers

Automation servers (automatable servers)

Automation controllers

OLE clipboard operations

OLE drag and drop operations

In-place editing

OLE user interface, including menu merging, pop-up menu for activated object, verbs on container's Edit menu

Compound file storage

Registration

Localized strings for international support

Type libraries


Printer Objects

Choose and configure a printer

Create a printer object

Create a printout object

Print a document

Print window contents

Printer Objects Overview


Validator Objects

Overriding validator member functions

Using data validator objects

Using the standard validator classes

Validator Objects Overview


Visual Basic Control Objects

Visual Basic Control Objects Overview

Accessing a VBX Control (ObjectWindows)

Handling VBX Control Messages (ObjectWindows)


Window Objects

Window Objects Overview

Constructing Window Objects

Setting Creation Attributes

Creating Window Interface Elements

Decorated Frame Windows

Frame Windows

Layout Windows

MDI Windows


ObjectWindows Classes and Structs
ObjectWindows Classes and Structures

Factory template classes

TAppDictionary

TApplication

TApplication::TXInvalidMainWindow

TAutoFactory

TBandInfo struct

TBitmap

TBitmapGadget

TBitSet

TBIVbxLibrary

TBrush

TButton

TButtonGadget

TButtonGadgetEnabler

TCelArray

TCharSet

TCheckBox

TChooseColorDialog

TChooseColorDialog::TData

TChooseFontDialog

TChooseFontDialog::TData

TClientDC

TClipboard

TClipboardViewer

TColor

TComboBox

TComboBoxData

TCommandEnabler

TCommonDialog

TControl

TControlBar

TControlGadget

TCreatedDC

TCursor

TDC

TDecoratedFrame

TDecoratedMDIFrame

TDesktopDC

TDialog

TDib

TDibDC

TDocManager

TDocTemplate

TDocTemplateT<D,V>

TDocument

TDocument::List

TDropInfo

TEdgeConstraint struct

TEdit

TEditFile

TEditSearch

TEditView

TEventHandler

TEventHandler::TEventInfo

TFileDocument

TFileOpenDialog

TFileSaveDialog

TFilterValidator

TFindDialog

TFindReplaceDialog

 TFindReplaceDialog::TData

TFloatingFrame

TFont

TFrameWindow

TGadget

TGadgetWindow

TGadgetWindowFont

TGauge

TGdiObject

TGdiObject::TXGdi

TGroupBox

THatch8x8Brush

THSlider

TIC

TIcon

TInputDialog

TInStream

TLayoutConstraint struct

TLayoutMetrics

TLayoutWindow

TListBox

TListBoxData struct

TListView

TLocaleString

TLookupValidator

TMDIChild

TMDIClient

TMDIFrame

TMemoryDC

TMenu

TMenu::TXMenu

TMenuDescr

TMenuItemEnabler

TMessageBar

TMetaFileDC

TMetaFilePict

TModule

TModule::TXInvalidModule

TOleAutoFactory

TOleClientDC

TOleDocument

TOleDocViewAutoFactory

TOleDocViewFactory

TOleFactory

TOleFactoryBase

TOleFrame

TOleLinkView

TOleMDIFrame

TOleView

TOleWindow

TOpenSaveDialog

TOutStream

TPaintDC

TPalette

TPaletteEntry

TPen

TPoint

TPointer<>

TPopupMenu

TPreviewPage

TPrintDC

TPrintDialog

TPrintDialog::TData struct

TPrinter

TPrinter::TXPrinter

TPrinterAbortDlg

TPrintout

TPrintPreviewDC

TProcInstance

TProfile

TPXPictureValidator

TRadioButton

TRangeValidator

TRect

TRegion

TReplaceDialog

TResId

TResponseTableEntry

TRgbQuad

TRgbTriple

TScreenDC

TScrollBar

TScrollBarData struct

TScroller

TSeparatorGadget

TSize

TSlider

TSortedStringArray

TStatic

TStatus

TStatusBar

TStorageDocument

TStream

TStringLookupValidator

TSystemMenu

TTextGadget

TTinyCaption

TToolBox

TUIHandle

TValidator

TValidator::TXValidator

TVbxControl

TVbxEventHandler

TView

TVSlider

TWindow

TWindow::TXWindow

TWindowAttr struct

TWindowDC

TWindowView

TXBase

TXCompatibility

TXOutOfMemory

TXOwl


ObjectWindows Hierarchy (Diagram 1 of 4)


ObjectWindows Hierarchy (Diagram 2 of 4)


ObjectWindows Hierarchy (Diagram 3 of 4)


ObjectWindows Hierarchy (Diagram 4 of 4)


ObjectWindows Typedefs
ObjectWindows Type Definitions

ObjectWindows Classes and Structs

Typedefs

TActionFunc typedef

TActionMemFunc typedef

TAnyDispatcher Typedef

TAnyPMF typedef

TCondFunc typedef

TCondMemFunc typedef

TEventHandler::TEqualOperator typedef


ObjectWindows Constants

ObjectWindows Classes and Structs

Constants

BF_xxxx Constants

CM_xxxx Edit Constants

CM_xxxx Edit File Constants

CM_xxxx Edit Replace Constants

CM_xxxx MDI Constants

dmxxxx Document Manager Mode Constants

dtxxxx Document Template Constants

ID_xxxx File Constants

ID_xxxx Printer Constants

IDA_EDITFILE Accelerator ID Constants

IDA_OLEVIEW OLE Accelerator ID Constants

IDM_EDITFILE Menu ID Constant

IDS_xxxx Document String ID Constants

IDS_xxxx Edit File ID Constants

IDS_xxxx Exception Messages

IDS_xxxx Listview ID Constants

IDS_xxxx Printer String ID Constants

IDS_xxxx Validator ID Constants

IDW_MDICLIENT Constant

IDW_FIRSTMDICHILD Constant

lmParent Constant

MAX_RSRC_ERROR_STRING Constant

pfxxxx Property Attribute Constants

Vnxxxx view notification constants

Voxxxx validator constants


ObjectWindows Macros

ObjectWindows Classes and Structs

Macros

_BUILDOWLDLL Macro

DECLARE_RESPONSE_TABLE Macro

DEFINE_DOC_TEMPLATE_CLASS Macro

DEFINE_RESPONSE_TABLE Macros

END_RESPONSE_TABLE Macro

EV_xxxx Macros

OLE Registration Macros

_OWLCLASS Macro

_OWLDATA Macro

_OWLDLL Macro

_OWLFAR Macro

_OWLFUNC Macro


ObjectWindows Enums
ObjectWindows Enumerated Types

ObjectWindows Classes and Structs

Enums

dnxxxx Document Message Enum

ofxxxx Document Open Enum

shxxxx Document Sharing Enum

TEventStatus enum

TMeasurementUnits enum

TPicResult enum

TRelationship enum

TTransferDirection enum

TWidthHeight enum

TWindowFlag enum

xs exception status enum


ObjectWindows Functions

ObjectWindows Classes and Structs

Functions

LongMulDiv Function

NBits Function

NColors Function

OWLGetVersion Function


BF_xxxx Button Flag Constants

See Also

Header File

checkbox.h

Description

Check box and radio button objects use the button flag constants to indicate the state of a selection box.

Button Flag Constants

Constant	Meaning

BF_CHECKED	Item is checked.

BF_GRAYED	Item is grayed.

BF_UNCHECKED	Item is unchecked.


See Also

TCheckbox::GetCheck

TCheckbox::SetCheck


BN_xxxx Button Message Constants

See Also

Header File

windows.h

Description

Mouse and radio button objects use the button message constants to indicate the state of a button.

Button Message Constants

Constant	Meaning

BN_CLICKED	Message sent when the user clicks a button

BN_DISABLE	Message sent when a button is disabled

BN_DOUBLECLICKED	Message sent when the user double-clicks a button

BN_HILITE	Message sent when the user highlights a button

BN_PAINT	Message sent when a button needs to be repainted

BN_UNHILITE	Message sent when the highlighting needs to be removed from a button


See Also

TRadioButton::BNClicked


CBN_xxxx Combo Box Message Constants

See Also

Header File

windows.h

Description

Combo box objects use these  message constants to indicate the state of the combo box.

Combo Box Message Constants

Constant	Meaning

CBN_CLOSEUP	Message sent when the list box of a combo box has closed

CBN_DBLCLK	Message sent when the user double-clicks a text string in the combo box

CBN_DROPDOWN	Message sent when the list box of a combo box drops down

CBN_EDITCHANGE	Message sent when the user changes text in the edit control portion of a combo box

CBN_EDITUPDATE	Message sent when edited text is going to be displayed

CBN_ERRSPACE	Message sent when the combo box is out of memory

CBN_KILLFOCUS	Message sent when the combo box loses the input focus

CBN_SELENDCANCEL	Message sent when the user's initial selection needs to be cancelled because the user has selected another control or closed the dialog box.

CBN_SELENDOK	Message sent if the user's selection is valid

CBN_SETFOCUS	Message sent when the combo box receives the input focus


See Also

TComboBox


CM_xxxx Edit Constants

Header File

window.rh

Description

These command-based member functions are invoked in response to a particular edit menu selection or command.

Command-Based Constants

Constant	Member function	Menu equivalent

CM_EDITCLEAR	TEdit::CMEditClear	Edit|Clear

CM_EDITCOPY	TEdit::CMEditCopy	Edit|Copy

CM_EDITCUT	TEdit::CMEditCut	Edit|Cut

CM_EDITDELETE	TEdit::CMEditDelete	Edit|Delete

CM_EDITPASTE	TEdit::CMEditPaste	Edit|Paste

CM_EDITUNDO	TEdit::CMEditUndo	Edit|Undo

CM_EXIT	TWindow::CmExit	File|Exit


CM_xxxx Edit File Constants

Header File

docview.rh

Description

These command-based member functions are invoked in response to open, close, print, and save commands.

Command-Based Constants

Constant	Member function	Menu equivalent

CM_FILECLOSE	File|Close

CM_FILENEW	TEditFile::CmFileNew	File|New

CM_FILEOPEN	TEditFile::CmFileOpen	File|Open

CM_FILEPRINT	File|Print

CM_FILEPRINTERSETUP	File|PrinterSetup

CM_FILEREVERT	TDocManager::CmFileRevert	File|Revert

CM_FILESAVE	TEditFile::CmFileSave	File|Save

CM_FILESAVEAS	TEditFile::CmFileSaveAs	File|Save As

CM_VIEWCREATE	TDocManager::CmViewCreate	File|View Create


CM_xxxx Edit Replace Constants

Header File

editsear.rh

Description

These command-based member functions are invoked when the corresponding find and replace command is received.

Command-Based Constants

Constant	Member function	Menu equivalent

CM_EDITFIND	TEditSearch::CMEditFind	Edit|Find

CM_EDITFINDNEXT	TEditSearch::CMEditFindNext	Edit|Find|Next

CM_EDITREPLACE	TEditSearch::CMEditReplace	Edit|Replace


CM_xxxx Edit View Constants

Header File

oleview.rh

Description

These command-based view functions are invoked in response to menu and accelerator key commands. The Edit|Verbs selection refers to one of the OLE-specific menu commands, such as Edit or Open.

Constant	Member function	Menu equivalent

CM_EDITPASTESPECIAL	TOleWindow::CmEditPasteSpecial	Paste|Special

CM_EDITPASTELINK	TOleWindow::CmEditPasteLink	Paste|Link

CM_EDITINSERTOBJECT	TOleWindow::CmEditInsertObject	Insert|Object

CM_EDITLINKS	TOleWindow::CmEditLinks	Edit|Links

CM_EDITOBJECT	TOleWindow::CeEditObject	Edit|Object

CM_EDITFIRSTVERB	TOleWindow::EvCommandEnable	Edit|Verbs

CM_EDITLASTVERB	TOleWindow::EvCommandEnable	Edit|Verbs

CM_EDITCONVERT	TOleWindow::CmEditConvert	Edit|Convert


CM_xxxx MDI Constants

Header File

mdi.rh

Description

These MDI functions are invoked when the corresponding MDI command message is received.

Command Message Constants

Constant	Member function	Menu equivalent

CM_ARRANGEICONS	TMDIClient::CmArrangeIcons	Window|Arrange Icons

CM_CASCADECHILDREN	TMDIClient::CmCascadeChildren	Window|Cascade

CM_CLOSECHILDREN	TMDIClient::CmCloseChildren	Window|Close All

CM_CREATECHILD	TMDIClient::CmCreateChild

CM_TILECHILDREN	TMDIClient::CmTileChildren	Window|Tile

CM_TILECHILDRENHORIZ	TMDIClient::CmTileChildren	Window|Tile


DECLARE_RESPONSE_TABLE Macro

See Also

Header File

eventhan.h

Description

Declares a response table in the class definition. To handle events for a class, you need to both declare a response table with this macro and define the response table using one of the DEFINE_RESPONSE_TABLE macros. For example, to declare a response table, use the following declaration, where the single parameter, Class, represents the name of the current class:

DECLARE_RESPONSE_TABLE(Class);

ObjectWindows' response tables define the relationship between a window message and a corresponding event-handling function. The description of TEventHandler has more information about how ObjectWindows associates a response table entry with the appropriate function.


See Also

DEFINE RESPONSE TABLE macros

END RESPONSE TABLE macro

TEventHandler


DEFINE_APP_DICTIONARY macro

See Also

Header File

appdict.h

Description

This macro defines an AppDictionary reference and object as needed for use in component DLLs and EXEs. Unless a user dictionary is specified, the macro defines the dictionary as OwlAppDictionary, which is a globally exported TAppDictionary. The macro is defined as follows:

#define DEFINE_APP_DICTIONARY(AppDictionary)


See Also

TAppDictionary


DEFINE_DOC_TEMPLATE_CLASS Macro

See Also

Header File

doctpl.h

Description

Creates a document template. Takes three arguments: the name of the document class that holds the data, the name of the view class that displays the data, and the name of the template class, and then associates the document with one or more views. The following example illustrates how you can associate document and view classes with new template classes.

DEFINE_DOC_TEMPLATE_CLASS(TFileDocument, TListView, ListTemplate);

DEFINE_DOC_TEMPLATE_CLASS(TFileDocument, TEditView, EditTemplate);


See Also

TDocTemplate


DEFINE_RESPONSE_TABLE Macros

See Also

Header File

eventhan.h

Description

Defines a response table. Takes one plus x number of arguments: one is the name of the class that is defining the response table and x is the immediate base class as well as any virtual base classes. Use the END_RESPONSE_TABLE macro to end the definition for the response table. Between the DEFINE_RESPONSE_TABLE macro and the END_RESPONSE_TABLE macro, insert the message response entries for the messages you want the class to handle. For example,

DEFINE_RESPONSE_TABLE1(TMyClass, TWindow)

  EV_WM_PAINT,

  EV_WM_LBUTTONDOWN,

END_RESPONSE_TABLE;

In this example, EV_WM_PAINT and EV_WM_LBUTTONDOWN illustrate the message response entries for the class TMyClass derived from TWindow. These macros call the corresponding event-handling functions, EvPaint and EvLButtonDown, respectively. Note that response tables are sometimes defined, but have no entries. In such cases, the base class's response table entries are searched for the appropriate event-handling function. You can also associate more than one message with an event-handling function.

The following table shows the form the DEFINE_RESPONSE_TABLE macro takes depending on the number of base classes.

Number of
Base Classes	Macro

0 	DEFINE_RESPONSE_TABLE(Class)

1	DEFINE_RESPONSE_TABLE(Class, Base)

2 	DEFINE_RESPONSE_TABLE2(Class, Base1, Base2)

3 	DEFINE_RESPONSE_TABLE3(Class, Base1, Base2, Base3)


See Also

DECLARE RESPONSE TABLE macro

END RESPONSE TABLE macro

TEventHandler


DLGC_xxxx Dialog Control Message Constants

See Also

Header File

windows.h

Description

 Indicate the kind of input that the dialog manager needs to process. Returned by EvGetDlgCode.

Dialog Control Message Constants

Constant	Meaning

DLGC_BUTTON	Indicates a button

DLGC_DEFPUSHBUTTON	Indicates a default button

DLGC_HASSETSEL	Indicates a range of characters in an edit control

DLGC_RADIOBUTTON	Indicates a radio button control message

DLGC_STATIC	Indicates a static control

DLGC_UNDEFPUSHBUTTON	Indicates a non-default push button control

DLGC_WANTALLKEYS	Indicates all keyboard input

DLGC_WANTARROWS	Indicates the direction keys

DLGC_WANTCHARS	Indicates all key code messages

DLGC_WANTMESSAGE	Indicates all keyboard input can be passed on to the control.

DLGC_WANTTAB	Indicates the TAB key


See Also

TButton::EvGetDlgCode

TCheckBox::EvGetDlgCode

TEdit::EvGetDlgCode

TListView::EvGetDlgCode

TSlider::EvGetDlgCode


dmxxxx Document Manager Mode Constants

See Also

Header File

docmanag.h

Description

Used by TDocManager to indicate if a document supports single or multiple open documents, and to indicate if it has file menu IDs.

Constant	Meaning

dmMenu	Sets IDs for file menu.

dmMDI 	Supports multiple open documents.

dmNoRevert	Disables the File|Revert menu command.

dmSaveEnable	Enables File|Save menu command.

dmSDI	Does not support multiple open documents.


See Also

TDocManager::TDocManager


dnxxxx Document Message Enum

See Also

Header File

docmanag.h

Description

Used by TDocManager to indicate that a document or view has been created or closed. You can set up response table entries for these messages using the EV_OWLVIEW or EV_OWLDOCUMENT macros.

Constant	Meaning

dnCreate	A new document or view has been created.

dnClose	A document or view has been closed.


See Also

TDocManager::TDocManager


dtxxxx Document Template Constants

See Also

Header File

locale.h

Description

Used by TDocument and TDocTemplate to create templates. Several constants are equivalent to the OFN_xxxx constants defined by Windows in commdlg.h.

Constant	Windows equivalent	Meaning

dtAutoDelete	Deletes the document when the last view is deleted.

dtAutoOpen	Opens a document upon creation.

dtCreatePrompt	(OFN_CREATEPROMPT)	Prompts the user before creating a document that does not currently exist.

dtDynRegInfo	Used to register a container or server for OLE 2 support. Indicates that the registration information table is dynamic not static.

dtFileMustExist	(OFN_FILEMUSTEXIST)	Lets the user enter only existing file names in the File Name entry field. If an invalid file name is entered, causes a warning message to be displayed.

dtHidden	Hides the template from the user's selection.

dtHideReadOnly	(OFN_HIDEREADONLY)	Hides the read-only check box.

dtNewDoc	Creates a new document with no path specified.

dtNoAutoView	Does not automatically create the default view type.

dtNoReadOnly	(OFN_NOREADONLYRETURN)	Returns the specified file as writeable.

dtNoTestCreate	(OFN_NOTESTFILECREATE)	Does not perform document-creation tests. The file is created after the dialog box is closed. If the application sets this flag, there is no check against write protection, a full disk, an open drive door, or network protection. For certain network environments, this flag should be set.

dtOverwritePrompt	(OFN_OVERWRITEPROMPT)	When the Save As dialog box is displayed, asks the user if it's OK to overwrite the file.

dtPathMustExist	(OFN_PATHMUSTEXIST)	Allows only valid document paths to be entered. If an invalid path name is entered, causes a warning message to be displayed.

dtProhibited	(OFN_ALLOWMULTISELECT)	Doesn't support these specified

(OFN_ENABLEHOOK)	Windows options.

(OFN_ENABLETEMPLATE)

(OFN_ENABLETEMPLATEHANDLE)

dtReadOnly	(OFN_READONLY)	Checks the read-only check box when the dialog box is created.

dtRegisterExt	Used to register a container or server for OLE 2 support. Registers an extension with this application.

dtSelected	Indicates the last selected template.

dtSingleUse	Indicates that the document is to be registered as a single use document.

dtSingleView	Provides only a single view for each document.

dtUpdateDir	Updates the directory with the directory specified in the dialog box.


See Also

TDocTemplate::GetFlags

TLocaleString

TDocument


END_RESPONSE_TABLE Macro

See Also

Header File

eventhan.h

Syntax

END_RESPONSE_TABLE;

Description

Indicates the end of a response table.  For each class that contains a response table, add this macro to the class definition.


See Also

DEFINE RESPONSE TABLE macro


EN_xxxx Edit Message Constants

Header File

windows.h

Description

 Indicate the state of an edit control in various situations: after a user has changed text, when the edit control receives the input focus, and so on.

Edit Message Constants

Constant	Meaning

EN_CHANGE	Message sent when the display is updated after changes have been made to the edit control

EN_ERRSPACE	Message sent when the edit control is out of memory

EN_HSCROLL	Message sent when the user clicks the horizontal scroll bar

EN_KILLFOCUS	Message sent when the edit control is losing the input focus

EN_MAXTEXT	Message sent when the text insertion is truncated

EN_SETFOCUS	Message sent when the edit control receives input focus

EN_UPDATE	Message sent when the edit control is going to display revised text

EN_VSCHOLL	Message sent when the user clicks the vertical scroll bar


EV_xxxx Macros

Header File

windowev.h

Description

Create response table entries that match events to member functions.

Macro	Meaning

EV_CHILD_NOTIFY(id,notifyCode,method)	Handles child ID notifications (for example, button, edit control, list box, combo box, and scroll bar notification messages) at the child's parent window. Passes no arguments.

EV_CHILD_NOTIFY_ALL_CODES	Passes all notifications to the response function and passes the notification code in as an argument.

EV_CHILD_NOTIFY_AND_CODE(id, notifyCode, method)	Handles child ID notifications at the child's parent window and passes the notification code as an argument.

EV_COMMAND(id, method)	Handler for menu selections, accelerator keys, and push buttons.

EV_COMMAND_AND_ID(id, method)	Handler for multiple commands using a single response function. Passes the menu ID in as an argument.

EV_COMMAND_ENABLE(id, method)	 Enables and disables commands such as buttons and menu items.

EV_MESSAGE(message, method)	General purpose macro for Windows WM_xxxx messages.

EV_NOTIFY_AT_CHILD(notifyCode, method)	Handles all child ID notifications at the child window.

EV_OWLDOCUMENT(id, method)	Handles new document notifications.

EV_OWLNOTIFY(id, method)	Generic document handler.

EV_OWLVIEW(id, method)	Handles view notifications.

EV_REGISTERED(str, method)	Handles registered MSG messages.

EV_VIEWNOTIFY	Sends a notification message from the document to the views.


GetApplicationObject function

See Also

Header File

appdict.h

Syntax

TApplication* GetApplicationObject(unsigned pid = 0);

Description

This global function is included mainly for backward compatibility with previous ObjectWindows applications. To find the application object associated with a process ID, GetApplicationObject calls TAppDictionary::GetApplication on an application dictionary. Used by EXEs or DLLs statically linking ObjectWindows, GetApplicationObject can return 0.


See Also

GetWindowPtr function

TAppDictionary::GetApplication


GetWindowPtr function

See Also

Header File

window.h

Syntax

TWindow* GetWindowPtr(HWND hWnd);

Description

This global function is included mainly for backward compatibility with previous ObjectWindows applications. First, GetWindowPtr calls the global function  GetApplicationObject to find the application. It then calls TApplication::GetWindowPtr to get the TWindow pointer associated with the window.


See Also

GetApplicationObject function

TApplication::GetWindowPtr


ID_xxxx File Constants

See Also

Header File

inputdia.rh

Description

Resource and control IDs for the input dialog box.

Constant 	Meaning

IDD_INPUTDIALOG	Resource ID number for the input dialog box

ID_INPUT	Control ID for the user input

ID_PROMPT	Control ID for the static text


See Also

TInputDialog::SetUpWindow


ID_xxxx Printer Constants

Header File

printer.rh

Description

Resource and control IDs for the printer abort dialog box.

Constant	Meaning

IDD_ABORTDIALOG	Resource ID number for the abort dialog box.

ID_TITLE 	Control ID for the selected printer driver.

ID_DEVICE	Control ID for the selected printer.

ID_PAGE	ID number for the page number text control.

ID_PORT	Control ID for the selected printer port.


IDA_EDITFILE Accelerator ID Constant

Header File

editfile.rh

Description

Resource ID for accelerator keys.

Constant	Meaning

IDA_EDITFILE	Resource ID for accelerator keys.


IDA_OLEVIEW OLE Accelerator ID Constant

Header File

oleview.rh

Description

Resource ID for accelerator keys.

Constant	Meaning

IDA_OLEVIEW	Resource ID for accelerator keys for OLE enabled applications.


IDM_EDITFILE Menu ID Constant

Header File

editfile.rh

Description

Resource ID for menu selections.

Constant	Meaning

IDM_EDITFILE	Resource ID for menu selections.


IDM_xxxx OLE Menu ID Constants

Header File

oleview.rh

Description

Menu IDs for OLE-enabled applications.

Constant	Meaning

IDM_OLEPOPUP	OLE enabled application pop-up menu

IDM_OLEVIEW	OLE enable application view menu selection


IDS_xxxx Edit View ID Constants

Header File

oleview.rh

Description

String constants used to respond to edit view commands.

Constant	Meaning

IDS_EDITOBJECT	Edit the object

IDS_EDITCONVERT	Convert the object

IDS_EXITSERVER	Exit the server application


IDS_Mode Constants

Header File

statusba.rh

Description

Resource and command IDs to use with TStatusBar.

Constant	Meaning

IDS_MODES	String resource to define mode On indicators

IDS_MODESOFF	String resource to define mode Off indicators


IDS_xxxx Document String ID Constants

String IDs that define resource IDs used to determine the status of the document.

Header File

docview.rh

Constant	Displays these messages

IDS_DOCCHANGED	If the document has been changed, displays the message, "Do you want to save the changes?"

IDS_DOCLIST  	Document is a document type.

IDS_DOCMANAGERFILE	This is a document manager file.

IDS_DUPLICATEDOC	This is a duplicate document.

IDS_NODOCMANAGER	There is no document manager.

IDS_NOMEMORYFORVIEW	Not enough memory to view the document

IDS_NOTCHANGED	The document has not been changed.

IDS_READERROR	Error while reading the file

IDS_UNTITLED	The file is untitled.

IDS_UNABLECLOSE	Document manager is unable to close the document.

IDS_UNABLEOPEN	Document manager is unable to open the document.

IDS_UNTITLED 	Document is untitled.

IDS_VIEWLIST 	Document is a view type.


IDS_xxxx Edit File ID Constants

Header File

editfile.rh

Description

String constants used by edit and file classes to display information about files.

Constant	Meaning

IDS_FILECHANGED	The text in the file has changed. Do you want to save the changes?

IDS_FILEFILTER	Use this filter to display text files.

IDS_UNABLEREAD	Unable to read the file from the disk.

IDS_UNABLEWRITE	Unable to write the file to the disk.

IDS_UNTITLEDFILE	The default window title unless the file is being edited.


IDS_xxxx Exception Message Constants

Header File

except.rh

Description

General and application exception message constants. When an exception occurs in the creation of a child window, for example, TWindow::Create calls TXWindow with an IDS_WINDOWCREATEFAIL message. The following list groups the constants according to message type:

Constant	Meaning

IDS_INVALIDMAINWINDOW	Invalid MainWindow

IDS_INVALIDMODULE	Invalid module specified for window

IDS_NOAPP	No application object

IDS_OKTORESUME	Resume in spite of error

IDS_OWLEXCEPTION	Unknown exception

IDS_OUTOFMEMORY	Out of memory

IDS_UNHANDLEDXMSG	Unhandled xmsg error

IDS_UNKNOWNERROR	Unknown error

IDS_UNKNOWNEXCEPTION	Unknown exception error

Owl 1 compatibility messages:

IDS_INVALIDCHILDWINDOW	Invalid child window

IDS_INVALIDCLIENTWINDOW	Invalid client window

IDS_INVALIDWINDOW	Invalid window

TXWindow messages:

IDS_CHILDCREATEFAIL	Child create fail for window

IDS_CHILDREGISTERFAIL	Child class registration fails for window

IDS_CLASSREGISTERFAIL	Class registration fails for window

IDS_LAYOUTCOMPLETE	Layout window failure

IDS_LAYOUTBADRELWIN	Layout window failure

IDS_MENUFAILURE 	Menu creation failure

IDS_PRINTERERROR	Printer error

IDS_VALIDATORSYNTAX	Validator syntax error

IDS_WINDOWCREATEFAIL	Create fail for window

IDS_WINDOWEXECUTEFAIL	Execute fail for window

GDI messages:

IDS_GDIALLOCFAIL	GDI allocate failure

IDS_GDICREATEFAIL	GDI creation failure

IDS_GDIDELETEFAIL	GDI object delete failure

IDS_GDIDESTROYFAIL	GDI object destroy failure

IDS_GDIFAILURE	GDI failure

IDS_GDIFILEREADFAIL	GDI file read failure

IDS_INVALIDDIBHANDLE	Invalid DIB handle

IDS_GDIRESLOADFAIL	GDI resource load failure


IDS_xxxx Listview ID Constants

Header File

listview.rh

Description

Define operations performed on views. These include clearing the document, inserting a new line, copying text to the Clipboard, and so on.

Constant	Meaning

IDS_LISTVIEW	Resource ID for listview constants.


IDS_xxxx Printer String ID Constants

Header File

printer.rh

Description

Constants used by printer classes to determine the printer status.

Constant	String displayed

IDS_PRNCANCEL	Printing is canceled.

IDS_PRNERRORCAPTION	Printer error occurred.

IDS_PRNERRORTEMPLATE	Document was not printed.

IDS_PRNGENERROR	Error encountered during printing.

IDS_PRNMGRABORT	Printing aborted in Print Manager.

IDS_PRNON	Printer is on.

IDS_PRNOUTOFDISK	Out of disk space.

IDS_PRNOUTOFMEMORY	Out of memory.


IDS_xxxx Validator ID Constants

Header File

validate.rh

Description

Defines several constants used by validator classes to determine the validator status.

Constant	Meaning

IDS_VALPXPCONFORM	Item doesn't conform to correct picture format.

IDS_VALINVALIDCHAR	Character isn't one of the valid entries.

IDS_VALNOTINRANGE	Entry isn't within the specified range.

IDS_VALNOTINLIS	String isn't found in the list of valid entries.


IDW_MDICLIENT Constant

Header File

framewin.h

Syntax

IDW_MDICLIENT

Description

Child ID constant used to identify MDI client windows.


IDW_FIRSTMDICHILD Constant

Header File

framewin.h

Syntax

IDW_FIRSTMDICHILD

Description

Child ID constant used to identify the first MDI client window.


LangXxxx_ID constants
LangXxxx ID constants

See Also

Header File

locale.h

Description

A language ID is 16-bit number representing a language. In ObjectComponents, a language ID is a value of type TLangId.

A language ID is composed of two parts. The ten low-order bits identify a language and the six high-order bits identify a dialect or sub-language. For example, a language ID can specify simply French, or make use of the upper bits to designate Belgian French, Swiss French, or Canadian French.

IDs for different languages are defined in the system header olenls.h. ObjectComponents defines constants to represent three common IDs:

Constant	Meaning

LangSysDefault  	The default language set for the system.

LangUserDefault 	The default language set for a particular user (which can differ from the system setting on multi-user systems.)

LangNeutral	A neutral setting signifying no particular locale. An application that receives this value uses its own default setting.


See Also

TLangId typedef

TLocaleString


LBN_xxxx List Box Message Constants

Header File

windows.h

Description

Indicate changes in the status of the list box.

Constant	Meaning

LBN_DBLCLK	Message sent when the user double-clicks a string in a list box

LBN_ERRSPACE	Message sent when the list box is out of memory

LBN_KILLFOCUS	Message sent when the list box is losing the input focus

LBN_SELCANCEL	Message sent when the user cancels the selection in a list box

LBN_SELCHANGE	Message sent when the user changes the selection in a list box

LBN_SETFOCUS	Message sent when the list box receives the input focus.


lmParent Constant

See Also

Header File

layoutco.h

Syntax

#define lmParent 0

Description

LmParent is used to construct layout metrics (for example, edge and size constraints).


See Also

TLayoutConstraint struct


LongMulDiv Function

See Also

Header File

scroller.h

Syntax

inline long LongMulDiv(long mul1, long mul2, long div1);

Description

TScroller uses this function to convert horizontal range values (XRange) from the scroll bar to horizontal scroll values (XScrollValue) and vice versa, or to convert vertical range values (YRange) from the scroll bar to vertical scroll values (YScrollValue) and vice versa.


See Also

TScroller


MAX_RSRC_ERROR_STRING Constant

Header File

except.h

Syntax

const int MAX_RSRC_ERROR_STRING = 255;

Description

Maximum number of characters possible for an error message.


MB_Xxxx Message Constants

See Also

Header File

windows.h

Description

Contain information about the style and behavior of a message dialog box. You can use these constants to determine the kinds of information displayed in a message dialog box.

Constant	Meaning

MB_OK	The message dialog box contains an OK push button.

MB_OKCANCEL	The message dialog box contains Cancel and OK push buttons.

MB_ABORTRETRYIGNORE	The message dialog box contains Abort, Retry, and Ignore push buttons.

MB_YESNOCANCEL	The message dialog box contains Yes, No and Cancel push buttons.

MB_YESNO	The message dialog box contains Yes and No push buttons.

MB_RETRYCANCEL	The message dialog box contains Retry and Cancel push buttons.

MB_ICONHAND	The message dialog box contains a stop sign icon.

MB_ICONQUESTION	The message dialog box contains a question mark.

MB_ICONEXCLAMATION	The message dialog box contains an exclamation mark.

MB_ICONASTERISK	The message dialog box contains an icon consisting of a lowercase letter i.

MB_ICONINFORMATION	The message dialog box contains an icon consisting of a lowercase letter i.

MB_ICONSTOP	The message dialog box contains a stop sign icon.

MB_ICONHAND	The message dialog box contains a stop-sign icon.

MB_DEFBUTTON1	The first button is the default button in the  message dialog box. This is always the case unless MB_DEFBUTTON2 or MB_DEFBUTTON3 is specified.

MB_DEFBUTTON2	The second button is the default button in the  message dialog box.

MB_DEFBUTTON3	The third button is the default button in the message dialog box.

MB_APPLMODAL	Before continuing to work in this window, the user must answer the message dialog box. However, the user can work in other windows. MB_APPLMODAL is the default unless MB_SYSTEMMODAL, MB_TASKMODAL, or MB_NOFOCUS is specified.

MB_SYSTEMMODAL	Before continuing to work in this window, the user must answer the message dialog box. Unless the application indicates MB_ICONHAND, the message box does not become modal until after it is created. The owning window and other windows can continue to receive messages. You can use MB_SYSTEMMODAL to notify the user of serious errors, such as lack of sufficient memory to run an application, that must be taken care of immediately.

MB_TASKMODAL	Before continuing to work in this window, the user must answer the message dialog box. However, the user can work in other windows. Unlike MB_APPLMODAL, all top-level windows in the current task are disabled. Use this constant when the calling application does not have a window handle available, and you want to prevent input to other windows in the current application without actually preventing the other applications from executing.


See Also

TDocument::PostError

TDocManager::PostDocError

TWindow::MessageBox


NBits Function

See Also

Header File

color.h

Syntax

uint16 NBits(long colors);

Description

Returns the bit count corresponding to the given color count.


See Also

NColors

TColor class


NColors Function

See Also

Header File

color.h

Syntax

int NColors(uint16 bitCount);

Description

Returns the color count corresponding to the given bit count, or -1 if the bit count is not supported by Windows. Bit counts currently supported are 1, 4, 8, and 24.


See Also

NBits

TColor class


ofxxxx Document Open Enum

See Also

Header File

docview.h

Description

Defines the document and open sharing modes used for constructing streams and storing data. Any constants that have the same functionality as those used by OLE 2.0 docfiles are indicated in the following table; for example, STGM_TRANSACTED, STGM_CONVERT, STGM_PRIORITY, and STGM_DELETEONRELEASE.

Although files are typically used for data storage, databases or spreadsheets can also be used. I/O streams rather than DOS use these bit values. Documents open the object used for storage in one of the following modes:

Constant	Meaning

ofParent	A storage object is opened using the parent's mode.

ofRead	A storage object is opened for reading.

ofWrite	A storage object is opened for writing.

ofReadWrite	A storage object is opened for reading and writing.

ofAtEnd	Seek to end-of-file when opened originally.

ofAppend	Data is appended to the end of the storage object.

ofTruncate	An already existing file is truncated.

ofNoCreate	Open fails if file doesn't exist.

ofNoReplace	Open fails if file already exists.

ofBinary	Data is stored in a binary, not text, format. Carriage returns are not stripped.

ofIosMask	All of the above bits are used by the ios class.

ofTransacted	Changes to the storage object are preserved until the data is either committed to permanent storage or discarded. (STGM_TRANSACTED)

ofPreserve	Backs up previous storage data using before creating a new storage object with the same name. (STGM_CONVERT)

ofPriority	Supports temporary, efficient reading before opening the storage. (STGM_PRIORITY)

ofTemporary	The storage or stream is automatically destroyed when it is destructed. (STGM_DELETEONRELEASE)


See Also

TStream

TInStream

TOutStream


pfxxxx Property Attribute Constants

See Also

Header File

docview.h

Description

Define document and view property attributes. Documents, views, and applications use these attributes to determine how to process a document or view.

Constant	Meaning

pfGetText	Property is accessible in a text format.

pfGetBinary	Property is accessible as a native nontext format.

pfConstant 	Property cannot be changed after the object is created.

pfSettable	Property can be set. Must supply a native format.

pfUnknown	Property is defined but unavailable for the object.

pfHidden 	Property should be hidden from the user during normal browsing. (Do not let the user see its name or value.)

pfUserDef 	Property has been user-defined at run time.


See Also

TDocument

TView


_BUILDOWLDLL Macro

See Also

Header File

owldefs.h

Syntax

_BUILDOWLDLL

Description

Used internally to control values for the _OWLCLASS, _OWLDATA, and _OWLFUNC macros. This macro is defined when the user's module is built as a DLL. It must be defined and included in ObjectWindows makefiles to build the ObjectWindows DLL.


See Also

_OWLDLL macro


_OWLCLASS Macro

Header File

owldefs.h

Syntax

_OWLCLASS

Description

Used internally by ObjectWindows to modify an entire class for use in a DLL. It is the ObjectWindows version of _RTLCLASS adjusted to export and import WIN32 DLLs.

For static WIN16 and WIN32 , the default models are used. When ObjectWindows is being built, this macro evaluates to _export for WIN16 and WIN32 DLLs. For WIN32 DLLs, this macro evaluates to _import and performs necessary operations for WIN32 DLLs. For WIN16 DLL use, this macro evaluates to _import, which is essentially the same as _huge.


_OWLDATA Macro

Header File

owldefs.h

Syntax

_OWLDATA

Description

The ObjectWindows version of _RTLDATA adjusted to export and import WIN32 DLLs for ObjectWindows. _OWLDATA modifies a specific data declaration.

For static WIN16 and WIN32, the default models are used. When ObjectWindows is being built, this macro evaluates to _export for WIN16 and WIN32 DLLs. For WIN32 DLLs, this macro evaluates to _import and performs necessary operations for WIN32 DLLs. For WIN16 DLLs, this macro evaluates to nothing.


_OWLDLL Macro

Header File

owldefs.h

Syntax

_OWLDLL

Description

_OWLDLL, which is automatically defined if _RTLDLL is turned on, controls values for the _OWLCLASS, _OWLDATA, and _OWLFUNC macros. It is also automatically defined if the user _OWLDLL module is used as a DLL from another user module. It must be defined if you are writing ObjectWindows applications or DLLs that use DLLs. This macro can also be turned on by a makefile.


_OWLFAR Macro

Header File

owldefs.h

Syntax

_OWLFAR

Description

The macro _OWLFAR is the ObjectWindows version of _RTLFAR adapted to promote far data pointers in DLLs for ObjectWindows.


_OWLFARVTABLE Macro

Header File

owldefs.h

Syntax

_OWLFARVTABLE

Description

Moves the ObjectWindows virtual function tables (vtables) out of the DGROUP of the data segment and stores them in the code segment. Use this macro in conjunction with the _OWLCLASS macro to add the _huge option when static models are compiled.


_OWLFASTTHIS Macro

Header File

owldefs.h

Syntax

_OWLFASTTHIS

Description

 The macro _OWLFASTTHIS causes _fastthis to be added to the _OWLCLASS macro so that all ObjectWindows classes use the fastthis calling convention for passing the this parameter in the registers. This macro, which has the same effect as using the -po compiler option, applies to 16-bit code only.


_OWLFUNC Macro

Header File

owldefs.h

Syntax

_OWLFUNC

Description

The ObjectWindows function version of _RTLFUNC adapted to export and import functions for building WIN32 DLLs for ObjectWindows. _OWLFUNC modifies a specific member or global function for use in a DLL.

For static WIN16 and WIN32 DLLs, the default models are used. When ObjectWindows is being built, this macro evaluates to _export for WIN16 and WIN32 DLLs. For WIN32 DLLs, this macro evaluates to _import and performs necessary operations for WIN32 DLLs. For WIN16 DLL use, this macro evaluates to nothing.


OWLGetVersion Function

Header File

owldefs.h

Syntax

unsigned short far _OWLFUNC OWLGetVersion();

Description

Returns the version number of the ObjectWindows library. The version number is represented as an unsigned short.


SB_Xxxx Scroll Bar Constants

Header File

windows.h

Description

The following constants define scroll bar modes:

Constant	Meaning

SB_BOTH	Displays or hides the horizontal and vertical scroll bars for a window.

SB_CTL	Displays or hides a scroll bar's control button.

SB_HORIZ	Displays or hides the horizontal scroll bars for a window.

SB_VERT	Displays or hides the vertical scroll bar for a window.


shxxxx Document Sharing Enum

Header File

docview.h

Description

The following file-sharing modes are available when opening document streams.

Constant	Meaning

shCompat	Used for noncompliant applications, but should be avoided if possible.

shNone	DENY_ALL functionality.

shRead 	DENY_WRITE functionality.

shWrite   	DENY_READ functionality.

shReadWrite 	DENY_NONE functionality

shDefault	Use stream implementation default value.

shMask  	Mask for file-sharing bits.


TActionFunc typedef

See Also

Header File

window.h

Syntax

typedef void(*TActionFunc)(TWindow* win, void* param);

Description

Passes a function pointer to TWindow::ForEach.


See Also

TWindow::ForEach


TActionMemFunc typedef

See Also

Header File

window.h

Syntax

typedef void(TWindow::*TActionMemFunc)(TWindow* win, void* param);

Description

Passes a member function pointer to TWindow::ForEach.


See Also

TWindow::ForEach


TAnyPMF typedef

Header File

dispatch.h

Syntax

typedef void(GENERIC::*TAnyPMF)();

Description

A generic pointer to a member function.


TAnyDispatcher Typedef

Header File

dispatch.h

Syntax

typedef LRESULT(*TAnyDispatcher)(GENERIC&, TAnyPMF, WPARAM, LPARAM);

Description

A message dispatcher type. All message dispatcher functions conform to this type and take four parameters:

A reference to an object

A pointer to the member function in which the signature varies according to the cracking that the function performs

WPARAM

LPARAM


Factory Template Classes (Object Windows)

See Also

Header File

olefacto.h

Description

The factory template classes create callback code for both automated and non automated Doc/View and non-Doc/view ObjectWindows applications. Use these factory template classes to make objects for embedding and linking. (That is, when an application object needs to be embedded within another container, the callback function is responsible for creating the embedded object.) Depending on the template arguments passed to the factory class, you obtain different kinds of factories designed to create the object you need. All the templetized classes, however, assume that the application is using a global AppDictionary (the application's dictionary), and a global Registrar (the TOcRegistrar pointer that manages registering the application in the database).

ObjectWindows includes several factory template classes, divided into two main categories: those designed for Doc/View applications and those designed for non-Doc/View applications. Although all these classes contain the same functions, they are designed to create different types of objects.

The factory class hierarchy chart illustrates the inheritance relationship among these classes.

Each class takes three arguments: the application class, the automation class, and the Doc/View class. The arguments indicate whether or not the application is a Doc/View application and whether or not the application is automated. The factory classes and their definitions include the following four classes.

TOleDocViewFactory class for Doc/View, non-automated, OLE components

template <class T> class TOleDocViewFactory

: public TOleFactoryBase<T, TOleFactoryDocView<T,
  TOleFactoryNoAuto<T>>>{};

TOleDocViewAutoFactory class for Doc/View, automated OLE components

template <class T> class TOleDocViewAutoFactory

: public TOleFactoryBase<T, TOleFactoryDocView<T,
  TOleFactoryAuto<T>>>{};

TOleFactory class for non-Doc/View, non-automated, OLE components

template <class T> class TOleFactory

: public TOleFactoryBase<T, TOleFactoryNoDocView<T,
  TOleFactoryNoAuto<T>>>{};

TOleAutoFactory class for non-Doc/View, automated OLE components

template <class T> class TOleAutoFactory

: public TOleFactoryBase<T, TOleFactoryNoDocView<T,
  TOleFactoryAuto<T>>>{};

For either a Doc/View or a non-Doc/View application, you need to register your application in your OwlMain function. The argument to TOcRegistrar (in this case, TOleFactory<TDrawApp>) constructs an object and converts it to a TComponentFactory type, using the operator TComponentFactory to create a function pointer. In reality, the object is never created because all the factory class's functions are static.

Pass your application object derived from TApplication as the parameter to TOleFactory, as the following code from STEP15.CPP illustrates:

int

OwlMain(int /*argc*/, char* /*argv*/ [])

{

  try {

    Registrar = new TOcRegistrar(AppReg, TOleFactory<TDrawApp>(),

                                 TApplication::GetCmdLine());

    if (Registrar->IsOptionSet(TOcCmdLine::AnyRegOption))

      return 0;

//If this is a normal exe server, run the application now; otherwise,

// wait until the factory is called.

    return Registrar->Run();

}

In general, the following steps, illustrated in the Factory Class Callback Flowchart, show the steps each factory class follows in the default callback code:

1.	The factory gets the application. This is the application object derived from TApplication. For a DLL server, there can be several instances of the object. Using TAppDictionary::GetApplication, the factory verifies whether or not there is an entry in the application dictionary for an application object for the current process.

2.	If the application does not exist, the factory creates the application object and tests to see if the application was created successfully before creating its corresponding TOcApp object. If the shutdown option flag is set, it then exits. (If the application has already been destroyed, the shutdown flag is set.)

3.	If the factory is passed a shutdown option flag (one of the TOcAppMode enum values), it then shuts down the application and calls the factory's DestroyApp function to destroy the application.

4.	If the application is automated, the factory creates a corresponding automation object.

5.	If the object ID is not zero, the factory creates the object and gets the OLE interface. Otherwise, it gets the application's OLE interface. At this point, the Doc/View and non-Doc/View processes differ because they need to create different types of objects. If the application is automated, the factory creates an automated helper object.

6.	The factory checks to see if the option flag amRun (one of the TOcAppMode enum values) is set, and, if so, it runs the application. This occurs if the application either was built as an .EXE or is a DLL running as an .EXE. If the amRun flag is not set and the application is an in-proc DLL server and should not be running, the factory just starts the application.

7.	The factory returns either the OLE interface for the object or 0 if no interface was requested or if an error occurred.

The factory can be called back to walk through this process several times:

1.	On the first callback, the factory creates the application, and if the amRun flag is set, it enters a message loop.

2.	On the second callback, OLE calls the factory to automate or embed or link an object. In the case of an embedded and/or linked object, this pass can occur one or more times. (In the case of an automation object, however, this second pass occurs only once because any subsequent requests pass through the automated application itself.)

3.	On the final callback, the factory shuts down the application.


See Also

TAutoFactory class

TAutoFactory::DestroyApp

TComponentFactory typedef

TOcAppMode enum

TOcRegistrar class

TOleFactoryBase class

TOleFactoryBase::DestroyApp

TOleFactoryBase::TComponentFactory


Factory Class Callback Flowchart


Mix-in Classes

Classes designed to be used in conjunction with other classes to provide special functionality or behavior. Mix-in classes are designed not to stand alone, but to be combined with other bases when declaring a new class. The new class is derived through multiple inheritance from the mix-in and other base classes.

For example, if you are building a frame window, you can derive your frame window class from both the base class TFrameWindow and the mix-in class TLayoutWindow to get the additional functionality of layout windows.

See Also

TClipboardViewer

TEventHandler enum

TOcModule

TTinyCaption


Registration Macros

See Also

Header File

locale.h

Description

The following macros take care of performing various OLE-related registration procedures. These macros simplify the process of building a registration table (a specific kind of lookup table) either for an automation server or for a non-automated application or document associated with a container or server. A collection of vital statistics about an object, the registration table provides an external description associated with an object. Some of the information goes into the system registry and is used by OLE. Some of the information is displayed in the File|Open dialog box when the user selects the Insert Object selection.

The registration macros build a TRegList structure containing entries of type TRegItem, a structure defined as follows:

struct TRegItem {

  char*  Key;              //Item name

  TLocaleString Value;    //String value for the item

};

Using these macros saves you the trouble of having to build the TRegItem and TRegList structures directly.

Although servers and containers use the same macros, they pass different kinds of information to the registration structures. The number of registration macros you use depends on the amount of information you want associated with your application and whether you want to set up a structure with document or application information.

Registration Macros

Macro	Meaning

BEGIN_REGISTRATION	Begins a registration macro table.

END_REGISTRATION	Ends a registration macro table.

REGDATA	Registers information about the application such as class ID, description, document filter, and debugger options.

REGDOCFLAGS	Registers a series of document flags. Required for a document registration table.

REGFORMAT	Registers a data format.

REGICON	Registers an icon.

REGITEM	Registers a customized format.

REGSTATUS	Registers an aspect status.

REGVERBOPT	Registers an option for a verb.

REGISTRATION_FORMAT_BUFFER	Sets the size of the buffer space needed for expansion.

REGDATA, the main macro used in the registration table, passes string data in its arguments. The REGFORMAT, REGDOCFLAG, REGICON, REGSTATUS, and REGVERBOPT macros format numeric values as string values.

For a list of which item names (referred to as keys) are required in the application and document registration tables, see Registration Keys. For information about how to use these macros in your OLE-enabled applications, see Registering a Linking And Embedding Server and Registering a Container. The sample applications REGTEST.CPP and STEP15DV.CPP on your distribution disk provide examples of registration tables designed for different kinds of applications and documents.


See Also

Registering a Linking And Embedding Server

Registration Keys.

Registering a Container

TLocaleString struct


BEGIN_REGISTRATION Macro

See Also	REGISTRATION Macros

Header File

locale.h

Syntax

BEGIN_REGISTRATION(regname)

Description

Indicates the beginning of a registration macro table. The macro takes one argument (regname), which is the name of the structure to be built. Within the registration table macro, there are several macros that build the registration structure. Depending on the type of application or document, different macros are used. The following example from STEP15.CPP registers the drawing pad as a server application and builds an AppReg structure:

BEGIN_REGISTRATION(AppReg)

  REGDATA(clsid,      "{5E4BD320-8ABC-101B-A23B-CE4E85D07ED2}")

  REGDATA(description,"OWL Drawing Pad Server")

END_REGISTRATION


See Also

END_REGISTRATION Macro

REGDATA Macro


END_REGISTRATION Macro

See Also	REGISTRATION Macros

Header File

locale.h

Syntax

END_REGISTRATION

Description

Indicates the end of a registration macro table. You can insert the registration macros within the BEGIN_REGISTRATION and END_REGISTRATION macros to build a registration structure.


See Also

BEGIN_REGISTRATION Macro


REGDATA Macro

See Also	REGISTRATION Macros

Header File

locale.h

Syntax

REGDATA(var,val)

Description

The main registration macro, REGDATA registers information about an application or a document. The macro always takes an item name (for example, clsid) and a corresponding string value (for example, 5E4BD320-8ABC-101B-A23B-CE4E85D07ED2). The following example from STEP15.CPP on your distribution disk passes the class ID and description to build an AppReg application registration structure:

BEGIN_REGISTRATION(AppReg)

  REGDATA(clsid, "{5E4BD320-8ABC-101B-A23B-CE4E85D07ED2}")

  REGDATA(description, "OWL Drawing Pad Server")

END_REGISTRATION

For an automation server application, the registration structure includes the following REGDATA macros:

BEGIN_REGISTRATION(myappreg)

 REGDATA(clsid,      "{01234567-1234-5678-1122-334455667788}")

 REGDATA(progid,     "MySample")

 REGDATA(description,"My Sample 1.0 Application")

 REGDATA(cmdline,    "/automation")

 REGDATA(version,    "1.2")

END_REGISTRATION

Each object that can be automated requires a unique program ID, a description, and a command-line argument that is placed on the server's command line. As usual, only one class ID is defined for the entire application. See the ObjectWindows Programmer's Guide for detailed information about how to register an automation server.

For each application registration structure, you may have one or more document registration structures. The following example uses the data from several REGDATA macros to build a DocReg registration structure:

BEGIN_REGISTRATION(mydocreg)

 REGDATA(description,"My Sample 1.0 Document")

 REGDATA(extension,  "myd") //Do not use a period before extension.

 REGDATA(directory,  "C:\temp")

 REGDATA(docfilter,  "*.drw;*.drx")

 ...//Insert additional macros here.

 REGDATA(debugger,   "tdw -t") // Sets debugger option

 REGDATA(progid,     "MyDocument") //For servers only

 REGDATA(menuname,   "My Document") //For servers only

 REGDATA(insertable,0) // For servers only

 REGDATA(usage,    ocrMultipleUse) // For servers only

 REGDATA(verb0,      "&Edit") //For servers only

 REGDATA(verb1,      "&Open") //For servers only

 REGDATA(verb2,      "&Play") //For servers only

 ...//Insert additional macros here.

END_REGISTRATION


See Also

BEGIN_REGISTRATION Macro

END_REGISTRATION Macro


REGITEM Macro

See Also	REGISTRATION Macros

Header File

locale.h

Syntax

REGITEM(key,val)

Description

Lets you write customized entries for the system registry. The following example from REGTEST.CPP registers conversion formats:

REGITEM("CLSID\\<clsid>\\Conversion\\Readable\\Main","FormatX,FormatY")

The first string is the registry key, which has one parameter (<clsid>). When the registry information is generated, an actual value is substituted for the template parameters.


See Also

BEGIN_REGISTRATION Macro

END_REGISTRATION Macro


REGFORMAT Macro

See Also	REGISTRATION Macros

Header File

locale.h

Syntax

REGFORMAT(i,f,a,t,d)

Description

The data formats that the server or container can support. REGFORMAT has the following parameters:

Parameter	Description

i	Order of priority for the designated data format, with 0 being the highest fidelity rendered.

f	The data format, for example, ocrText, ocrTiff, ocrDib, and so on.  (ocrxxxx Clipboard Constants describes the data formats.)

a	The format used to present the data

t	Medium to use to transfer the data, such as ocrMfPict (METAFILEPICT structure), ocrGDI (GDI object such as a bitmap), ocrIStream (Stream object in a compound file), and so on. (ocrxxxx Medium Constants describes the medium formats.)

d	Whether or not data is provided as well as received in the designated format. The accepted values are ocrGet (imports data in the specified format), ocrSet (exports data in the specified format), or ocrGetSet (both exports and imports data in the specified format).

For example, STEP15DV.CPP registers several clipboard formats:

REGFORMAT(0, ocrEmbedSource,  ocrContent,  ocrIStorage,  ocrGet)

REGFORMAT(1, ocrMetafilePict, ocrcontent, ocrMfPict, ocfSet)

The later code generates the string "format1, 3, 1, 1056,1". Although you could enter the string yourself, it is much easier to use the enumerated values.

To build a registration structure, use REGFORMAT within the BEGIN_REGISTRATION and END_REGISTRATION macros in a registration macro table. Any formats registered using REGFORMAT are also registered automatically on the Windows Clipboard. You can register your own formats by inserting a string indicating your own format. For example,

REGFORMAT(2, "ANewFormat", ocrContent, ocrIStorage, ocrGetSet)

To provide names for your own formats, call TOleFrame::AddUserFormatName. This function associates a clipboard data format with the description of the data format as it appears to users in the Help text of the Paste Special dialog box.


See Also

BEGIN_REGISTRATION Macro

ocrxxxx Clipboard Constants

ocrxxxx Medium Constants

TOleFrame::AddUserFormatName


REGSTATUS Macro

See Also	REGISTRATION Macros

Header File

locale.h

Syntax

REGSTATUS(a,f)

Description

Indicates the way in which the view (the aspect) of an object behaves. REGSTATUS has the following arguments:

Parameter	Description

a	The content of the object.

f	One of the ocrxxxx Object Status enum values indicating the status of the object, such as ocrOnlyIconic, ocrActivateWhenVisible, and so on.

The object can be defined to have many different behaviors. For example, an object registered as ocrActivateWhenVisible is active whenever it is visible.

Servers that support linked and embedded objects use this macro to register the behavior an object exhibits when it is viewed. This behavior is referred to as the aspect status, or simply aspect, of the object.

The sample program REGTEST.CPP on your distribution disk includes the following REGSTATUS macros:

REGSTATUS(all, ocrNoSpecialRendering)

REGSTATUS(icon, ocrOnlyIconic)

The first macro registers flags for all aspects of the object. The second macro registers flags for the iconic aspect of the object. (The icon used in the REGSTATUS macro must have been defined and registered.)


See Also

BEGIN_REGISTRATION Macro

REGICON Macro

ocrxxxx Object Status Constants


REGVERBOPT Macro

See Also	REGISTRATION Macros

Header File

locale.h

Syntax

REGVERBOPT(v,mf,sf)

Description

Registers the actions a server can perform on its objects. The arguments control how the verbs appear on the container's menu. The macro has the following arguments:

Parameter	Description

v	The verb key, for example, verb1 or verb2.

mf	A value that describes how a server's verbs appear on the container's menu. This value must be one of the ocrxxxx Verb Menu constants, such as ocrGrayed, which makes the verb appear gray on the menu and disables the verb.

sf	A value that tells the container how to use the verb. This value must be one of the ocrxxxx Verb Attribute constants, such as ocrNeverDirties, which indicates that the verb never modifies the object. These options can be ORed together.

The sample program REGTEST.CPP on your distribution disk includes the following REGVERBOPT macro:

REGVERBOPT(verb1, ocrGrayed, ocrOnContainerMenu | ocrNeverDirties)

These verb options are optional and are only valid if the verb is registered in the document registration table for the server application. To register the verb, use

REGDATA(verb1, "&Open")


See Also

BEGIN_REGISTRATION Macro

ocrxxxx Verb Attribute Constants

ocrxxxx Verb Menu Constants


REGICON Macro

See Also	REGISTRATION Macros

Header File

*locale.h

Syntax

REGICON(i)

Description

Registers an icon so the object is displayed as an icon. The sample program REGTEST.CPP on your distribution disk includes the following REGICON macro:

REGICON(1)

The macro takes one argument, the index of the default icon to use. This argument indicates which icon is to be retrieved from the resource file when the document is displayed as an icon.


See Also

BEGIN_REGISTRATION Macro


REGDOCFLAGS Macro

See Also	REGISTRATION Macros

Header File

locale.h

Syntax

REGDOCFLAGS(i)

Description

Indicates options for the document and defines the characteristics of document templates. The REGDOCFLAGS arguments tell the document manager how to display and manage the documents and views. Although for backward compatibility you can still pass this information to the document template by using the separate parameters in the constructor, newer programs should use the REGFORMAT, REGDOCFLAGS, and REGDATA macros to create a document template object.

The sample program REGTEST.CPP on your distribution disk includes the following REGDOCFLAGS macro declaration within the document registration structure:

BEGIN_REGISTRATION(mytplreg)

 REGDATA(description,"My Sample Draw View")

 REGDATA(filter,     "*.drw;*.drx")

 REGDATA(defaultext, "dvw")

 REGDATA(directory,  0)

 REGDOCFLAGS(dtAutoDelete | dtUpdateDir | dtCreatePrompt)

END_REGISTRATION

The arguments to REGDOCFLAGS define the document's characteristics. In the case of dtAutoDelete, for example, the document is deleted when the last view is deleted:

Certain documents must be registered with different options. For example, to register a Doc/View application used with a TOleDocument object, you must specify the dtRegisterExt and dtAutoOpen flags. If this is a Doc/View application, and if the document template is not hidden, you must register the description, filter, and extension.


See Also

BEGIN_REGISTRATION Macro

REGFORMAT Macro

REGDATA Macro

dtxxxx Document Template Constants


REGISTRATION_FORMAT_BUFFER Macro

REGISTRATION Macros

Header File

locale.h

Syntax

REGISTRATION_FORMAT_BUFFER(n);

Description

Allocates space in memory (n) for the expansion of the values passed in the registration macros that control the formatting of a document or application. Generally, allow 10 bytes for each value passed in the REGFORMAT macro in addition to the space required for strings passed in the REGSTATUS, REGVERBOPT, REGICON, or REGFORMAT macros. For example, the sample program, STEP15.CPP uses this macro to declare 100 bytes of space:

REGISTRATION_FORMAT_BUFFER(100);


TApplication Class

OWL Hierarchy	Inheritance

Header File

applicat.h

Description

Derived from TModule, TApplication acts as an object-oriented stand-in for an application module. TApplication and TModule supply the basic behavior required of an application. TApplication member functions create instances of a class, create main windows, and process messages.

To create an OLE-enabled Doc/View application, you need to derive your application from both TApplication and TOcModule.

Public Data Members

HACCEL HAccTable;

HINSTANCE hPrevInstance;

int nCmdShow;

Type Definitions

xs exception status enum

Public Constructors and Destructor

TApplication(const char far* name = 0, TModule*& gModule = ::Module, TAppDictionary* appDict = 0);

TApplication(const char far* name, HINSTANCE hInstance, HINSTANCE hPrevInstance, const char far* cmdLine, int cmdShow, TModule*& gModule = ::Module, TAppDictionary* appDict = 0);

~TApplication();

Public Member Functions

int BeginModal(TWindow* window, int flags = MB_APPLMODAL);

bool BWCCEnabled() const;

virtual bool CanClose();

void Condemn(TWindow* win);

bool Ctl3dEnabled()const;

void EnableBWCC(bool enable = true, uint Language = 0);

void EnableCtl3d(bool enable = true);

void EnableCtl3dAutosubclass(bool enable);

void EndModal(int result);

bool Find(TEventInfo &, TEqualOperator = 0);

TModule* GetBWCCModule() const;

TModule* GetCtl3dModule() const;

TDocManager* GetDocManager();

TFrameWindow* GetMainWindow();

TWindow* GetWindowPtr(HWND hWnd) const;

void GetWinMainParams();

virtual int MessageLoop();

void PostDispatchAction();

virtual void PreProcessMenu(HMENU hmenu);

virtual bool ProcessAppMsg(MSG& msg);

bool PumpWaitingMessages();

int QueryThrow();

void ResumeThrow();

virtual int Run();

static void SetWinMainParams(HINSTANCE hInstance, HINSTANCE hPrevInstance, const char far* cmdLine, int cmdShow);

void SuspendThrow(xalloc& x);

void SuspendThrow(xmsg& x);

void SuspendThrow(TXOwl& x);

void SuspendThrow(int);

void Uncondemn(TWindow* win);

Protected Data Members

bool BreakMessageLoop;

int MessageLoopResult;

Protected Member Functions

virtual bool IdleAction(long idleCount);

virtual void InitApplication();

virtual void InitInstance();

virtual void InitMainWindow();

TFrameWindow* SetDocManager(TDocManager* docManager);

TFrameWindow* SetMainWindow(TFrameWindow* window);

virtual int TermInstance(int status);


TApplication::HAccTable

See Also	TApplication

Syntax

HACCEL HAccTable;

Description

Included to provide backward compatibility, HAccTable holds a handle to the current accelerator table being used by the application. New applications should instead use the accelerator table handle TWindowAttr::AccelTable for each window object in the application.


See Also

TWindow::LoadAcceleratorTable

TWindowAttr struct


TApplication::hPrevInstance

TApplication

Syntax

HINSTANCE hPrevInstance;

Description

Contains the handle of the previously executing instance of the Windows application. If hPrevInstance is 0, there was no previously executing instance when this instance began execution. Under Win32, this value is always 0.


TApplication::nCmdShow

TApplication

Syntax

int nCmdShow;

Description

Indicates how the main window is to be displayed (either maximized or as an icon). These correspond to the WinMain parameter nCmdShow. nCmdShow can contain one of the following constants:

Constant	Meaning

SW_SHOWDEFAULT	Shows the default SW_xxxx command.

SW_HIDE	Hides the window.

SW_MINIMIZE	Minimizes the specified window.

SW_SHOW	Activates a window using current size and position.

SW_SHOWMAXIMIZED	Displays a maximized window.

SW_SHOWMINIMIZED	Displays a minimized window.

SW_SHOWNA	Displays window in its current state.

SW_SHOWNOACTIVATE	Displays the window as an icon.

SW_SHOWNORMAL	Displays a window in its original size and position.

SW_SHOWSMOOTH	Shows a window by updating it in a bitmap and then copying the bits to the screen.


xs Exception Status Enum

TApplication

Header File

applicat.h

Syntax

enum {xsUnknown, xsBadCast, xsBadTypeid, xsMsg, xsAlloc, xsOwl};

Description

These bit flags define the types of exceptions that are caught and suspended.  SuspendThrow and QueryThrow return the values of these bit flags.

The following table shows the xs exception enum constants:

Constant	Meaning

xsUnknown	Unknown exception

xsBadCast 	Bad_cast exception

xsBadTypeid	Bad_typeid exception

xsMsg	Any exception derived from xmsg

xsAlloc	xalloc exception

xsOwl	TXOwl exception


TApplication Public Constructors and Destructor

See Also	TApplication

Syntax 1

TApplication(const char far* name = 0, TModule*& gModule = ::Module, TAppDictionary* appDict = 0);

Description

Creates a new TApplication object named name. You can use gModule to specify the global module pointer that points to this application. The  appDict parameter specifies which dictionary this application will insert itself into. To override the default ObjectWindows TAppDictionary object, pass a pointer to a user-supplied appDict object.

Syntax 2

TApplication(const char far* name, HINSTANCE hInstance, HINSTANCE hPrevInstance, const char far* cmdLine, int cmdShow, TModule*& gModule = ::Module, TAppDictionary* appDict = 0);

Description

Creates a TApplication object with the application name (name), the application instance handle (instance), the previous application instance handle (prevInstance), the command line invoked (cmdLine), and the main window show flag (cmdShow). The  appDict parameter specifies which dictionary this application will insert itself into. To override the default ObjectWindows TAppDictionary object, pass a pointer to a user-supplied appDict object

If you want to create your own WinMain, use this constructor because it provides access to the various arguments provided by WinMain. You can use gModule to to specify the global module pointer that points to this application.

Destructor

~TApplication();

Description

~TApplication destroys the TApplication object.


See Also

TApplication::nCmdShow

TModule


TApplication::BeginModal

See Also	TApplication

Syntax

int BeginModal(TWindow* window, int flags = MB_APPLMODAL);

Description

Called to begin a modal window's modal message loop. After determining which window to disable, BeginModal saves the current status of the window, disables the window, calls MessageLoop, and then reenables the window when the message loop is finished. The flags determine how BeginModal treats the window. flags can be one of the following values:

Constant	Meaning

MB_APPLMODAL	The window to be disabled (which is usually an ancestor of the modal window) is identified by window. If window is 0, no window is disabled.

MB_SYSTEMMODAL	The window to become system modal is identified by window.

MB_TASKMODAL	All top-level windows are disabled, and window is ignored. BeginModal returns -1 if an error occurs.


See Also

TWindow


TApplication::BWCCEnabled

TApplication

Syntax

bool BWCCEnabled();

Description

Indicates if the Borland Custom Controls library (BWCC) is enabled. Returns true if BWCC is enabled and false if BWCC is disabled.


TApplication::CanClose

See Also	TApplication

Syntax

virtual bool CanClose();

Description

Returns true if it is OK for the application to close. By default, CanClose calls the CanClose member function of its main window and returns true if both the main window and the document manager (TDocManager) can be closed. If any of the CanClose functions return false, the application does not close.

This member function is seldom redefined; closing behavior is usually redefined in the main window's CanClose member function, if needed.


See Also

TWindow::CanClose


TApplication::Condemn

TApplication

Syntax

void Condemn(TWindow* win);

Description

Performs window cleanup.


TApplication::Ctl3dEnabled

See Also	TApplication

Syntax

bool Ctl3dEnabled() const;

Description

Returns true if the Microsoft 3-D Controls Library DLL is enabled. This DLL gives controls  a three-dimensional look and feel.


See Also

TApplication::EnableCtl3d

TApplication::EnableCtl3dAutosubclass


TApplication::EnableBWCC

See Also	TApplication

Syntax

void EnableBWCC(bool enable = true, uint Language = 0);

Description

Loads and registers either BWCC.DLL if you are running 16-bit applications or BWCC32.DLL if you are running 32-bit applications. By default, BWCC is enabled. To disable BWCC, set enable to false.


See Also

TDialog


TApplication::EnableCtl3d

See Also	TApplication

Syntax

void EnableCtl3d(bool enable = true);

Description

Enables or disables the use of the CTL3D DLL. If enable is true, EnableCtl3d loads and registers the CTL3D.DLL if it is not already enabled.


See Also

TApplication::Ctl3dEnabled

TApplication::EnableCtl3dAutosubclass


TApplication::EnableCtl3dAutosubclass

See Also	TApplication

Syntax

void EnableCtl3dAutosubclass(bool enable);

Description

Enables or disables CTL3D's use of autosubclassing if CTL3D is already enabled using Ctl3dEnabled. If autosubclassing is enabled, any non-ObjectWindows dialog boxes have a 3-D effect. The common dialog classes and TDocManager use this function both to turn on autosubclassing before creating a non-ObjectWindows dialog box to make it three-dimensional and to turn off autosubclassing immediately after the dialog box is destroyed.


See Also

TDialog::EvCtlColor

TApplication::EnableCtl3d

TApplication::Ctl3dEnabled


TApplication::EndModal

TApplication

Syntax

void EndModal(int result);

Description

Called to end a modal window's modal message loop. Sets result to -1 if an error occurs.


TApplication::Find

See Also	TApplication

Syntax

bool Find(TEventInfo &, TEqualOperator = 0);

Description

Because TApplication has no event table itself, it defers event handling to the DocManager. If a DocManager has been installed, Find calls TDocManager to handle events.


See Also

TEventHandler::TEventInfo


TApplication::GetBWCCModule

TApplication

Syntax

TModule* GetBWCCModule() const;

Description

Returns a pointer to the enabled Borland Windows Custom Controls library (BWCC) module.


TApplication::GetCtl3dModule

TApplication

Syntax

TModule* GetCtl3dModule() const;

Description

Returns a pointer to the enabled Ctl3d module.


TApplication::GetDocManager

See Also	TApplication

Syntax

TDocManager* GetDocManager();

Description

Returns a pointer to the document manager object that invoked the application.


See Also

TApplication::SetDocManager

TDocManager


TApplication::GetMainWindow

See Also	TApplication

Syntax

TFrameWindow* GetMainWindow();

Description

Returns a pointer to the application's main window.


See Also

TApplication::SetMainWindow

TFrameWindow


TApplication::GetWindowPtr

See Also	TApplication

Syntax

TWindow* GetWindowPtr(HWND hWnd) const;

Description

Retrieves a TWindow pointer associated with the handle to a window (hWnd), allowing more than one application to share the same HWND.


See Also

TWindow::GetWindowPtr


TApplication::GetWinMainParams

See Also	TApplication

Syntax

void GetWinMainParams();

Description

Initializes a static instance of an application. ObjectWindows OwlMain uses this function to support static application instances.


See Also

TApplication::SetWinMainParams


TApplication::MessageLoop

TApplication

Syntax

virtual int MessageLoop();

Description

Operates the application's message loop, which runs during the lifetime of the application. MessageLoop queries for messages. If one is received, it processes it by calling ProcessAppMsg. If the query returns without a message, MessageLoop calls IdleAction to perform some processing during the idle time. MessageLoop calls PumpWaitingMessages to get and dispatch waiting messages. MessageLoop can be broken if BreakMessageLoop is set by EndModal.


TApplication::PostDispatchAction

TApplication

Syntax

void PostDispatchAction();

Description

If TApplication's message loop is not used, this function should be called after each message is dispatched


TApplication::PreProcessMenu

See Also	TApplication

Syntax

virtual void PreProcessMenu(HMENU hmenu);

Description

Your application can call PreProcessMenu to process the main window's menu before it is displayed.


See Also

TDocmanager::EvPreProcessMenu

TMenu::TMenu


TApplication::ProcessAppMsg

See Also	TApplication

Syntax

virtual bool ProcessAppMsg(MSG& msg);

Description

Checks for any special processing that is required for modeless dialog box, accelerator, and MDI accelerator messages. Calls the virtual TWindow::PreProcessMsg function of the window receiving the message. If your application does not create modeless dialog boxes, does not respond to accelerators, and is not an MDI application, you can improve performance by overriding this member function to return false.


See Also

MSG struct


TApplication::PumpWaitingMessages

TApplication

Syntax

bool PumpWaitingMessages();

Description

Called by MessageLoop, PumpWaitingMessages processes and dispatches all waiting messages until the queue is empty. It also sets BreakMessageLoop when a WM_QUIT message is received.


TApplication::QueryThrow

TApplication

Syntax

int QueryThrow();

Description

Tests to see if an exception is suspended and returns one or more of the bit flags in the xs exception status enum.


TApplication::ResumeThrow

TApplication

Syntax

void ResumeThrow();

Description

Checks and rethrows suspended exceptions. Call this function any time you reenter ObjectWindows code from exception-unsafe code where an exception could have been thrown.


TApplication::Run

TApplication

Syntax

virtual int Run();

Description

Initializes the instance, calling InitApplication for the first executing instance and InitInstance for all instances. If the initialization is successful, Run calls MessageLoop and runs the application. If exceptions are thrown outside the message loop, Run catches these exceptions.

If an error occurs in the creation of a window, Run throws a TXWindow exception. If Status is assigned a nonzero value (which ObjectWindows uses to identify an error), a TXCompatibility exception is thrown.


TApplication::SetDocManager

See Also	TApplication

Syntax

TFrameWindow* SetDocManager(TDocManager* docManager);

Description

Sets a pointer to the document manager object that invoked the application.


See Also

TApplication::GetDocManager

TDocManager

TFrameWindow


TApplication::SetMainWindow

See Also	TApplication

Syntax

TFrameWindow* SetMainWindow(TFrameWindow* window);

Description

Sets up a new main window and sets the window's WM_MAINWINDOW flag.


See Also

TApplication::GetMainWindow

TFrameWindow


TApplication::SetWinMainParams

See Also	TApplication

Syntax

static void SetWinMainParams(HINSTANCE hInstance, HINSTANCE hPrevInstance, const char far* cmdLine, int cmdShow);

Description

The ObjectWindows default WinMain function calls SetMainWinParams so that TApplication can store the parameters for future use. To construct an application instance, WinMain calls the OwlMain function that is in the user's code. As it is being constructed, the application instance can fill in the parameters using those set earlier by SetMainWinParams.


See Also

TApplication::GetWinMainParams


TApplication::SuspendThrow

TApplication

Syntax 1

void SuspendThrow(xalloc& x);

Description

Saves xalloc exception information.

Syntax 2

void SuspendThrow(xmsg& x);

Description

Saves xmsg exception information.

Syntax 3

void SuspendThrow(TXOwl& x);

Description

Saves a copy of a TXOwl exception.

Syntax 4

void SuspendThrow(int);

Description

Sets the xs exception status enum bit flags to the specified exception (for example, Bad_cast or Bad_typeid).


TApplication::Uncondemn

See Also	TApplication

Syntax

void Uncondemn (TWindow* win);

Description

Removes condemned children from the list of condemned windows.


See Also

TWindow


TApplication::BreakMessageLoop

See Also	TApplication

Syntax

bool BreakMessageLoop;

Description

Causes the current modal message loop to break and terminate. If the current modal message loop is the main application, and your program sets BreakMessageLoop, your main application terminates.


See Also

TApplication::EndModal

TApplication::MessageLoop

TApplication::PumpWaitingMessages


TApplication::MessageLoopResult

TApplication

Syntax

int MessageLoopResult;

Description

Set by a call to EndModal, MessageLoopResult contains the value that is returned by MessageLoop and BeginModal.


TApplication::IdleAction

See Also	TApplication

Syntax

virtual bool IdleAction(long idleCount);

Description

ObjectWindows calls IdleAction when no messages are waiting in the queue to be processed. You can override IdleAction to do background processing. However, the default action is to give the main window a chance to do idle processing as long as IdleAction returns true. idleCount specifies the number of times IdleAction has been called between messages.


See Also

TFrameWindow::IdleAction


TApplication::InitApplication

TApplication

Syntax

virtual void InitApplication();

Description

ObjectWindows calls InitApplication to initialize the first instance of the application. For subsequent instances, this member function is not called.

The following sample program calls InitApplication the first time an instance of the program begins.

class TTestApp : public TApplication {

   public:

     TTestApp(): TApplication("Instance Tester")

       {strcpy(WindowTitle, "Additional Instance");}

   protected:

      char WindowTitle[20];

   void InitApplication() {strcpy(WindowTitle, "First Instance");}

   void InitMainWindow() {MainWindow = new TFrameWindow(0, WindowTitle);}

};

static TTestApp App;


TApplication::InitInstance

See Also	TApplication

Syntax

virtual void InitInstance();

Description

Performs each instance initialization necessary for the application. Unlike InitApplication, which is called for the first instance of an application, InitInstance is called whether or not there are other executing instances of the application. InitInstance calls InitMainWindow, and then creates and shows the main window element by TWindow::Create and TWindow::Show. If the main window cannot be created, a TXInvalidMainWindow exception is thrown.

If you redefine this member function, be sure to explicitly call TApplication::InitInstance.


See Also

TApplication::Run

TModule::MakeWindow


TApplication::InitMainWindow

TApplication

Syntax

virtual void InitMainWindow();

Description

By default, InitMainWindow constructs a generic TFrameWindow object with the name of the application as its caption. You can redefine InitMainWindow to construct a useful main window object of TFrameWindow (or a class derived from TFrameWindow) and store it in MainWindow. The main window must be a top-level window; that is, it must be derived from TFrameWindow. A typical use is

virtual void TMyApp_InitMainWindow(){

  SetMainWindow(TMyWindow(NULL, Caption));

}

InitMainWindow can be overridden to create your own custom window.


TApplication::TermInstance

TApplication

Syntax

virtual int TermInstance(int status);

Description

Handles the termination of each executing instance of an ObjectWindows application.


TApplication::TXInvalidMainWindow Class

TApplication	OWL Hierarchy	Inheritance

Header File

applicat.h

Description

A nested class, TXInvalidMainWindow describes an exception that results from an invalid Window. This exception is thrown if there is not enough memory to create a window or a dialog object. TApplication::InitInstance throws this exception if it can't initialize an instance of an application object.

Public Constructor

TXInvalidMainWindow();

Public Member Functions

virtual TXOwl* Clone();

virtual void Throw();


TXInvalidMainWindow Public Constructor

TApplication::TXInvalidMainWindow

Syntax

TXInvalidMainWindow();

Description

Constructs a TXInvalidMainWindow object with a default IDS_INVALIDMAINWINDOW message.


TXInvalidMainWindow::Clone
TApplication::TXInvalidMainWindow::Clone

TApplication::TXInvalidMainWindow

Syntax

virtual TXOwl* Clone();

Description

Makes a copy of the exception object. Clone must be implemented in any class derived from TXOwl.


TXInvalidMainWindow::Throw
TApplication::TXInvalidMainWindow::Throw

TApplication::TXInvalidMainWindow

Syntax

virtual void Throw();

Description

Throws the exception object. Throw must be implemented in any class derived from TXOwl..


TAppDictionary Class

See Also 	OWL Hierarchy

Header File

appdict.h

Description

A TAppDictionary is a dictionary of associations between a process ID and an application object. A process ID identifies a process: a program (including all its affiliated code, data, and system resources) that is loaded into memory and ready to execute. A TAppDictionary object supports global application lookups using the global  GetApplicationObject function or TAppDictionary's GetApplication function. If you do not define an application dictionary, ObjectWindows provides a default, global application dictionary that is exported. In fact, for .EXEs, this global application dictionary is automatically used.

TAppDictionary includes a TEntry struct, which stores a process ID and the corresponding application object associated with the ID. The public member functions add, find, and remove the entries in the application dictionary.

If you are statically linking ObjectWindows, you do not have to explicitly create an application dictionary because the default global ObjectWindows application dictionary is used. However, when writing a DLL component that is using ObjectWindows in a DLL, you do need to create your own dictionary. To make it easier to define an application dictionary, ObjectWindows includes a macro DEFINE_APP_DICTIONARY, which automatically creates or references the correct dictionary for your application.

Although this class is transparent to most users building EXEs, component DLLs need to create an instance of a TApplication class for each task that they service. This kind of application differs from an .EXE application in that it never runs a message loop. (All the other application services are available, however.)

Although a component may consist of several DLLs, each with its own TModule,  the component as a whole has only one TApplication for each task. A TAppDictionary, which is used for all servers (including DLL servers) and components, lets users produce a complete, self-contained application or component. By using a TAppDictionary, these components can share application objects.

When 16-bit ObjectWindows is statically linked with an .EXE or under Win32, with per- instance data, the TAppDictionary class is implemented as a wrapper to a single application pointer. In this case, there is only one TApplication that the component ever sees.

To build a component DLL using the ObjectWindows DLL, a new TAppDictionary object must be constructed for that DLL. These are the steps an application must follow in order to associate the component DLL with the TAppDictionary, the application, and the window class hierarchy:

1.	 Use the DEFINE_APP_DICTIONARY macro to construct an instance of TAppDictionary. Typically, this will be a static global in one of the application's modules (referred to as "AppDictionary"). The DEFINE_DICTIONARY macro allows the same code to be used for EXEs and DLLs.

DEFINE_APP_DICTIONARY(AppDictionary);

2.	Construct a generic TModule and assign it to the global ::Module. This is the default provided in the ObjectWindows' LibMain function.

LibMain(...)

  ::Module  = new TModule(0, hInstance);

3.	When each TApplication instance is constructed, pass a pointer to the TAppDictionary as the last argument to ensure that the application will insert itself into this dictionary. In addition, for 16 bit DLLs, the gModule argument needs to be supplied with a placeholder value because the Module construction has already been completed at this point, as a result of the process performed in step 2 above.

TApplication* app = new TMyApp(..., app, AppDictionary);

4.	If the Doc/View model is used, supply the application pointer when constructing the TDocManager object.

SetDocManager(new TDocManager(mode, this));

5.	When a non-parented window (for example, the main window) is being constructed, pass the application as the module.

SetMainWindow(new TFrameWindow(0, "", false, this));

Type Definitions

struct TEntry {

 unsigned  Pid;

 TApplication* App;

};

typedef void TEntryIterator(*TEntryIterator)(TEntry&);

Public Constructors and Destructors

TAppDictionary();

~TAppDictionary();

Public Member Functions

void Add(TApplication* app, unsigned pid = 0);

void Condemn(TApplication* app);

bool DeleteCondemned();

TApplication* GetApplication(unsigned pid = 0);

void Iterate(TEntryIterator iter);

void Remove(TApplication* app);

void Remove(unsigned pid);


See Also

TApplication::GetWindowPtr

TWindow::GetWindowPtr

DEFINE_APP_DICTIONARY macro


TAppDictionary Public Constructor and Destructor

TAppDictionary

Constructor

TAppDictionary();

Description

Constructs a TAppDictionary object.

Destructor

~TAppDictionary();

Description

Destroys the TAppDictionary object and calls DeleteCondemned to clean up the condemned applications.


TAppDictionary::Add

See Also	TAppDictionary

Syntax

void Add(TApplication* app, unsigned pid = 0);

Description

Adds an application object (app) and corresponding process ID to this dictionary. The default ID is the current process's ID.


See Also

TAppDictionary::Remove


TAppDictionary::TEntry struct

See Also	TAppDictionary

Syntax

struct TEntry {

 unsigned  Pid;

 TApplication* App;

};

Description

An application dictionary entry that associates a process ID (Pid) with an application (App). The dictionary is indexed by Pid and can have only 1 entry per process ID.


See Also

TAppDictionary::TEntryIterator typedef


TAppDictionary::TEntryIterator

See Also	TAppDictionary

Syntax

typedef void(*TEntryIterator)(TEntry&);

Description

A dictionary iterator function pointer type that receives a reference to an entry. You can supply a function of this type to the Iterate function to iterate through the entries in the dictionary.


See Also

TAppDictionary::TEntry struct

TAppDictionary::Iterate


TAppDictionary::GetApplication

TAppDictionary

Syntax

TApplication* GetApplication(unsigned pid = 0);

Description

Looks up and returns the application associated with a given process ID. The default ID is the ID of the current process. If no application is associated with the process ID, GetApplication returns 0.


TAppDictionary::Iterate

See Also	TAppDictionary

Syntax

void Iterate(TEntryIterator iter);

Description

Iterates through the entries in the application dictionary, calling the iter  callback function for each entry.


See Also

TAppDictionary::TEntryIterator


TAppDictionary::Remove

See Also	TAppDictionary

Syntax 1

void Remove(TApplication* app);

Description

Searches for the dictionary entry using the specified application (app). Then removes a given application and process ID entry from this dictionary, but does not delete the application object.

Syntax 2

void Remove(unsigned pid);

Description

Searches for the dictionary entry using the specified process ID (pid). Then removes a given application and its associated process ID entry from this dictionary, but does not delete the application.


See Also

TAppDictionary::Add


TAppDictionary::Condemn

TAppDictionary

Syntax

void Condemn(TApplication* app);

Description

Marks an application in this dictionary as condemned by zeroing its process ID so that the application can be deleted later when DeleteCondemned is called.


TAppDictionary::DeleteCondemned

See Also	TAppDictionary

Syntax

bool DeleteCondemned();

Description

Deletes all condemned applications from the dictionary. If no applications remain in the dictionary, DeleteCondemned returns true.


See Also

TAppDictionary::Condemn


TAutoFactory<> Class

See Also	Inheritance

Header File

olefacto.h

Description

A template class, TAutoFactory<>  creates callback code for ObjectWindows classes. The application class is passed as the argument to the template. By itself, TAutoFactory<> does not provide linking or embedding support for ObjectWindows automated applications.

Although TAutoFactory<> simplifies the process of creating the callback function, you can write your own callback function or provide alternate implementation for any or all of TAutoFactory<>'s functions.

Public Member Functions

operator TComponentFactory();

static T* CreateApp(uint32 options);

static void DestroyApp(T* app);

static IUnknown* Create(IUnknown* outer, uint32 options, uint32 id);


See Also

TComponentFactory typedef

TOcRegistrar class

Factory Template Classes

TOleFactoryBase class


TAutoFactory::TComponentFactory

TAutoFactory

Syntax

operator TComponentFactory();

Description

Converts the object into a pointer to the factory. ObjectComponents uses this pointer to create the automated object.


TAutoFactory::CreateApp

See Also	TAutoFactory

Syntax

static T* CreateApp(uint32 options);

Description

CreateApp creates a new automated application. By default, it creates a new application of template type T with no arguments. The options argument is one of the TOcAppMode enum values, for example, amRun, amAutomation, and so on that indicate the application's mode when running.


See Also

TAutoFactory::DestroyApp

TOcAppMode enum


TAutoFactory::DestroyApp

See Also	TAutoFactory

Syntax

static void DestroyApp(T* app);

Description

Destroys the previously created application referred to in app.


See Also

TAutoFactory::CreateApp


TAutoFactory::Create

See Also	TAutoFactory

Syntax

static IUnknown* Create(IUnknown* outer, uint32 options, uint32 id);

Description

Create is a TComponentFactory callback function that creates or destroys the application or creates objects. If an application object does not already exist, Create creates a new one. The outer argument points to the OLE 2 IUnknown  interface with which this object aggregates itself. If outer is 0, the new object is not aggregated, or it will become the main object.

The options argument indicates the application's mode while it is running. The values for options are either set from the command line or set by ObjectComponents. They are passed in by the "Registrar" to this callback. The application looks at these flags to know how to operate, and the factory callback looks at them to know what to do. For example, a value of amExeMode indicates that the server is running as an .EXE either because it was built as an .EXE or because it is a .DLL that was launched by an .EXE stub and is now running as an executable program. See TOcAppMode enum for a description of the possible values for the options argument.

If the application already exists, Create returns the application's OLE interface and registers the options from TOcAppMode enum which contains OLE-related flags used in the application's command line. For example, the amAutomation flag tells the server to register itself as a single-user application. (In general, these flags tell the application whether it has been run as a server, whether it needs to register itself, and so on.)

The id argument, which is not used for TAutoFactory, is always 0.


See Also

TAutoFactory::DestroyApp

TOcAppMode enum


TBandInfo struct

See Also	OWL Hierarchy

Header File

dc.h

Description

An ObjectWindows struct, TBandInfo is used to pass information to a printer driver that supports banding. TBandInfo is declared as follows:

struct TBandInfo {

bool HasGraphics;

bool HasText;

TRect GraphicsRect;

};

HasGraphics is true if graphics are (or are expected to be) on the page or in the band; otherwise, it is false.

HasText is true if text is (or is expected to be) on the page or in the band; otherwise, it is false.

GraphicsRect defines the bounding region for all graphics on the page.


See Also

TPrintDC::BandInfo

TPrintDC::NextBand


TButtonGadgetEnabler Class

OWL Hierarchy	Inheritance

Header File

buttonga.cpp

Description

Derived from TCommandEnabler, TButtonGadgetEnabler serves as a command enabler for button gadgets. The functions in this class modify the text, check state, and appearance of a button gadget.

Public Constructor

TButtonGadgetEnabler(HWND hWndReceiver, TButtonGadget* g);

Protected Data Member

TButtonGadget* gadget;

Public Member Functions

void Enable(bool enable);

void SetText(const char far*);

void SetCheck(int state);


TButtonGadgetEnabler Public Constructor

TButtonGadgetEnabler

Syntax

TButtonGadgetEnabler(HWND hWndReceiver, TButtonGadget* g);

Description

Constructs a TButtonGadgetEnabler for the specified gadget. hWndReceiver is the window receiving the message.


TButtonGadgetEnabler::gadget

TButtonGadgetEnabler

Syntax

TButtonGadget* gadget;

Description

The button gadget being enabled or disabled.


TButtonGadgetEnabler::Enable

TButtonGadgetEnabler

Syntax

void Enable(bool enable);

Description

Overrides TCommandEnable::Enable. Enables or disables the keyboard, mouse input, and appearance of the corresponding button gadget.


TButtonGadgetEnabler::SetText

TButtonGadgetEnabler

Syntax

void SetText(const char far*)

Description

Overrides TCommandEnable::SetText. Changes the text of the corresponding button gadget.


TButtonGadgetEnabler::SetCheck

TButtonGadgetEnabler

Syntax

void  SetCheck(int state)

Description

Overrides TCommandEnable::SetCheck. Changes the check state of the corresponding button gadget.


TBitmap Class

OWL Hierarchy	Inheritance

Header File

gdiobjec.h

Description

TBitmap is the GDI bitmap class derived from TGdiObject. TBitMap can construct a bitmap from many sources. TBitmap objects are DDBs (device-dependent bitmaps), which are different from the DIBs (device-independent bitmaps) represented by TDib objects.

Public Constructors

TBitmap(HBITMAP handle, TAutoDelete autoDelete = NoAutoDelete);

TBitmap(const TClipboard& clipboard);

TBitmap(const TBitmap& bitmap);

TBitmap(int width, int height, uint8 planes=1, uint8 bitCount=1, void far* bits=0);

TBitmap(const BITMAP far* bitmap);

TBitmap(const TDC& Dc, int width, int height, bool discardable = false);

TBitmap(const TDC& Dc, const TDib& dib, uint32 usage=CBM_INIT);

TBitmap(const TMetaFilePict& metaFile, TPalette& palette, const TSize& size);

TBitmap(const TDib& dib, const TPalette* palette = 0);

TBitmap(HINSTANCE instance, TResID resID);

Public Member Functions

uint8 BitsPixel() const;

uint32 GetBitmapBits(uint32 count, void far* bits) const;

bool GetBitmapDimension(TSize& size) const;

bool GetObject(BITMAP far& bitmap) const;

int Height() const;

TClipboard& operator <<(TClipboard& clipboard, TBitmap& bitmap);

operator HBITMAP() const;

uint8 Planes() const;

uint32 SetBitmapBits(uint32 count, const void far* bits);

bool SetBitmapDimension(const TSize& size, TSize far* oldSize=0);

void ToClipboard(TClipboard& clipboard);

int Width() const;

Protected Constructor

TBitMap();

Protected Member Functions

void Create(const TDib& dib, const TPalette &palette);

void Create(const TBitmap& src);


TBitmap Public Constructors

See Also	TBitmap

Form 1

TBitmap(HBITMAP handle, TAutoDelete autoDelete = NoAutoDelete);

Form 2

TBitmap(const TClipboard& clipboard);

Form 3

TBitmap(const TBitmap& bitmap);

Form 4

TBitmap(int width, int height, uint8 planes=1, uint8 bitCount=1, void far* bits=0);

Form 5

TBitmap(const BITMAP far* bitmap);

Form 6

TBitmap(const TDC& Dc, int width, int height, bool discardable = false);

Form 7

TBitmap(const TDC& Dc, const TDib& dib, uint32 usage=CBM_INIT);

Form 8

TBitmap(const TMetaFilePict& metaFile, TPalette& palette, const TSize& size);

Form 9

TBitmap(const TDib& dib, const TPalette* palette = 0);

Form 10

TBitmap(HINSTANCE instance, TResID resID);

Description

Form 1: Creates a TBitmap object and sets the Handle data member to the given borrowed handle. The ShouldDelete data member defaults to false, ensuring that the borrowed handle will not be deleted when the C++ object is destroyed.

Form 2: Creates a TBitmap object with values from the given Clipboard.

Form 3: Creates a copy of the given bitmap object.

Form 4: Creates a bitmap object from bitCount bits in the bits buffer with the given width, height, and planes argument values.

Form 5: Creates a bitmap object with the values found in the given bitmap structure.

Form 6: Creates a bitmap object for the given device context with the given argument values.

Form 7: Creates a bitmap object for the given device context with the given dib and usage argument values.

Form 8: Creates a bitmap object from the given metaFile using the given palette and size arguments.

Form 9: Creates a bitmap object from the given dib and palette arguments. A working palette constructed from the DIB's color table is used if no palette is supplied. The default system palette can also be passed using &TPalette::GetStock(TPalette::Default);

Form 10: Creates a bitmap object for the given application instance from the given resource.


See Also

TClipBoard::GetClipboardData

TDC

TDib

TGdiObject::Handle

TGdiObject::ShouldDelete

TPalette

BITMAP struct


TBitmap::BitsPixel

See Also	TBitmap

Syntax

uint8 BitsPixel() const;

Description

Returns the number of bits per pixel in this bitmap.


See Also

TBitmap::GetObject


TBitmap::GetBitmapBits

TBitmap

Syntax

uint32 GetBitmapBits(uint32 count, void far* bits) const;

Description

Copies up to count bits of this bitmap to the buffer bits.


TBitmap::GetBitmapDimension

See Also	TBitmap

Syntax

bool GetBitmapDimension(TSize& size) const;

Description

Retrieves the size of this bitmap (width and height, measured in tenths of millimeters) and sets it in the size argument. Returns true if the call is successful; otherwise returns false.


See Also

TSize


TBitmap::GetObject

See Also	TBitmap

Syntax

bool GetObject(BITMAP far& bitmap) const;

Description

Retrieves data (width, height, and color format) for this bitmap and sets it in the given BITMAP structure. To retrieve the bit pattern, use GetBitmapBits.


See Also

TBitMap::GetBitmapBits

BITMAP struct


TBitmap::Height

See Also	TBitmap

Syntax

int Height() const;

Description

Returns the height of this bitmap.


See Also

TBitmap::GetObject


TBitmap::operator <<

See Also	TBitmap

Syntax

TClipboard& operator <<(TClipboard& clipboard, TBitmap& bitmap);

Description

Copies the given bitmap to the given clipboard argument. Returns a reference to the resulting Clipboard, which allows normal chaining of <<.


See Also

TClipboard


TBitmap::operator HBITMAP()

TBitmap

Syntax

operator HBITMAP() const;

Description

Typecasting operator. Converts this bitmap's Handle to type HBITMAP (the data type representing the handle to a physical bitmap).


TBitmap::Planes

See Also	TBitmap

Syntax

uint8 Planes() const;

Description

Returns the number of planes in this bitmap.


See Also

TBitmap::GetObject


TBitmap::SetBitmapBits

TBitmap

Syntax

uint32 SetBitmapBits(uint32 count, const void far* bits);

Description

Copies up to count bits from the bits buffer to this bitmap.


TBitmap::SetBitmapDimension

See Also	TBitmap

Syntax

bool SetBitmapDimension(const TSize& size, TSize far* oldSize=0);

Description

Sets the size of this bitmap from the given size argument (width and height, measured in tenths of millimeters). The previous size is set in the oldSize argument. Returns true if the call is successful; otherwise returns false.


See Also

TSize


TBitmap::ToClipboard

See Also	TBitmap

Syntax

void ToClipboard(TClipboard& clipboard);

Description

Copies this bitmap to the given Clipboard.


See Also

TClipboard::SetClipboardData


TBitmap::Width

See Also	TBitmap

Syntax

int Width() const;

Description

Returns the width of this bitmap.


See Also

TBitmap::GetObject


TBitmap Protected Constructors

TBitmap

Syntax

TBitMap();

Description

Protected constructor for a TBitmap object.


TBitmap::Create

See Also	TBitmap

Syntax

void Create(const TDib& dib, const TPalette &palette);

void Create(const TBitmap &src);

Description

Creates a bitmap handle from the given argument objects.


See Also

TDib

TPalette


TBitmapGadget Class

See Also	OWL Hierarchy	Inheritance

Header File

bitmapga.h

Description

Derived from TGadget, TBitmapGadget is a simple gadget that can display an array of bitmap images one at a time.

Public Constructor And Destructor

TBitmapGadget(TResId bmpResId, int id, TBorderStyle borderStyle, int numImages,int startImage);

~TBitmapGadget();

Public Member Functions

int SelectImage(int imageNum, bool immediate);

void SysColorChange();

Protected Member Functions

void GetDesiredSize(TSize& size);

void Paint(TDC& dc);

void SetBounds(TRect& r);


See Also

TGadget

TBitmap


TBitmapGadget Public Constructors and Destructor
TBitmapGadget Public Constructor and Destructor

TBitmapGadget

Constructor Syntax

TBitmapGadget(TResId bmpResId, int id, TBorderStyle borderStyle,
int numImages, int startImage);

Description

Constructs a TBitmapGadget and sets the current image to the beginning image (startImage) in the array of images. Then, sets the border style to the current TGadget border style and numImages to the number of images in the array.

Destructor Syntax

~TBitmapGadget();

Description

Deletes the array of images.


TBitmapGadget::SelectImage

TBitmapGadget

Syntax

int SelectImage(int imageNum, bool immediate);

Description

Determines the current image and repaints the client area if the image has changed. Updates the client area if the image has changed.


TBitmapGadget::SysColorChange

TBitmapGadget

Syntax

void SysColorChange();

Description

When the system colors have been changed, SysColorChange is called by the gadget window's EvSysColorChange so that bitmap gadgets can be rebuilt and repainted.


TBitmapGadget::GetDesiredSize

TBitmapGadget

Syntax

void GetDesiredSize(TSize& size);

Description

Calls TGadget::GetDesiredSize, which determines how big the bitmap gadget can be. The gadget window sends this message to query the gadget's size. If shrink-wrapping is requested, GetDesiredSize returns the size needed to accommodate the borders and margins. If shrink-wrapping is not requested, it returns the gadget's current width and height. TGadgetWindow needs this information to determine how big the gadget needs to be, but it can adjust these dimensions if necessary. If WideAsPossible is true, then the width parameter (size.cx) is ignored.


TBitmapGadget::Paint

See Also	TBitmapGadget

Syntax

void Paint(TDC& dc);

Description

Paints the gadget's border and the contents of the bitmap.


See Also

TGadget::Paint


TBitmapGadget::SetBounds

See Also	TBitmapGadget

Syntax

void SetBounds(TRect& r);

Description

Calls TGadget::SetBounds and passes the dimensions of the bitmap gadget. SetBounds informs the control gadget of a change in its bounding rectangle.


See Also

TGadget::SetBounds


TBitSet Class

OWL Hierarchy	Inheritance

Header File

bitset.h

Description

TBitSet sets or clears a single bit or a group of bits. You can use this class to set and clear option flags and to retrieve information about a set of bits. The class TCharSet performs similar operations for a string of characters.

Constructors

TBitSet();

TBitSet(const TBitSet& bs);

Public Member Functions

void DisableItem(int item);

void DisableItem(const TBitSet& bs);

void EnableItem(int item);

void EnableItem(const TBitSet& bs);

int Has(int item);

int TBitSet::IsEmpty();

TBitSet& operator +=(int item);

TBitSet& operator +=(const TBitSet& bs);

TBitSet& operator -=(int item);

TBitSet& operator -=(const TBitSet& bs);

TBitSet& operator &=(const TBitSet&);

TBitSet& operator |=(const TBitSet&);

TBitSet operator ~(const TBitSet&);


TBitSet Public Constructors

TBitSet

Syntax 1

TBitSet();

Description

Constructs a TBitSet object.

Syntax 2

TBitSet(const TBitSet& bs);

Description

Constructs a TBitSet object as a copy of another TBitSet.


TBitSet::DisableItem

TBitSet

Syntax 1

void DisableItem(int item);

Description

Clears a single bit at item.

Syntax 2

void DisableItem(const TBitSet& bs);

Description

Clears the set of bits enabled in bs.


TBitSet::EnableItem

TBitSet

Syntax 1

void EnableItem(int item);

Description

Sets a single bit at item.

Syntax 2

void EnableItem(const TBitSet& bs);

Description

Sets the set of bits enabled in bs.


TBitSet::Has

TBitSet

Syntax

int Has(int item);

Description

Is nonzero if item is in the set of bits.


TBitSet::IsEmpty

TBitSet

Syntax

int TBitSet::IsEmpty();

Description

Is nonzero if the set is empty; otherwise, is 0.


TBitSet::operator +=

TBitSet

Syntax 1

TBitSet& operator +=(int item);

Description

Calls EnableItem to set a bit in the copied set. Returns a reference to the copied TBitSet object.

Syntax 2

TBitSet& operator +=(const TBitSet& bs);

Description

Calls EnableItem to set the bits enabled in bs. Returns a reference to the copied TBitSet object.


TBitSet::operator -=

TBitSet

Syntax 1

TBitSet& operator -=(int item);

Description

Calls DisableItem to clear a bit in the set. Returns a reference to the copied TBitSet object.

Syntax 2

TBitSet& operator -=(const TBitSet& bs);

Description

Calls DisableItem to clear the bits enabled in bs. Returns a reference to the copied TBitSet object.


TBitSet::operator &=

TBitSet

Syntax

TBitSet& operator &=(const TBitSet&);

Description

ANDs all the bits in the copied set and returns a reference to the copied TBitSet object.


TBitSet::operator |=

TBitSet

Syntax

TBitSet& operator |=(const TBitSet&);

Description

ORs all of the bits in the copied set and returns a reference to the copied TBitSet object.


TBitSet::operator ~

TBitSet

Syntax

TBitSet operator ~(const TBitSet&);

Description

Returns the set of bits that is the opposite of a specified set of bits. For example, if the set of bits is 01010101, the returned set is 10101010. Returns a reference to the copied TBitSet object.


TBIVbxLibrary Class

OWL Hierarchy	Inheritance

Header File

vxbctl.h

Description

Virtually derived from TModule, TBIVbxLibrary handles loading and initializing of BIVBX10.DLL. If you want to use VBX controls, construct a TBIVbxLibrary object with the same scope as your application.  For example,

int OwlMain(int, char**)

{

  TBIVbxLibrary vbxLib;

  return TTestApp().Run();

}

Public Constructor and Destructor

TBIVbxLibrary();

~TBIVbxLibrary();


TBIVbxLibrary Public Constructor and Destructor

TBIVbxLibrary

Syntax

TBIVbxLibrary();

Description

Constructs a TBIVbxLibrary object.

Destructor Syntax

~TBIVbxLibrary();

Description

Destroys a TBIVbxLibrary object.


TBrush Class

OWL Hierarchy	Inheritance

Header File

gdiobjec.h

Description

The GDI Brush class is derived from TGdiObject. TBrush provides constructors for creating solid, styled, or patterned brushes from explicit information. It can also create a brush indirectly from a borrowed handle.

Public Constructors

TBrush(HBRUSH handle, TAutoDelete autoDelete = NoAutoDelete);

TBrush(TColor color);

TBrush(TColor color, int style);

TBrush(const TBitmap& pattern);

TBrush(const TDib& pattern);

TBrush(const LOGBRUSH far* logBrush);

Public Member Functions

bool GetObject(LOGBRUSH far& logBrush) const;

operator HBRUSH const();

bool UnrealizeObject();


TBrush Public Constructors

See Also	TBrush

Form 1

TBrush(HBRUSH handle, TAutoDelete autoDelete = NoAutoDelete);

Form 2

TBrush(TColor color);

Form 3

TBrush(TColor color, int style);

Form 4

TBrush(const TBitmap& pattern);

Form 5

TBrush(const TDib& pattern);

Form 6

TBrush(const LOGBRUSH far* logBrush);

Description

Form 1: Creates a TBrush object and sets the Handle data member to the given borrowed handle. The ShouldDelete data member defaults to false, ensuring that the borrowed handle will not be deleted when the C++ object is destroyed.

Form 2: Creates a solid TBrush object with the given color. To save a brush creation this constructor uses a cache that can detect any color that matches a stock color.

Form 3: Creates a hatched TBrush object with the given style and color.

Form 4: Creates a patterned TBrush object with the given pattern.

Form 5: Creates a patterned TBrush object with the given DIB pattern.

Form 6: Creates a TBrush object with values from the given logBrush.


See Also

TBitmap

TColor

TDib

TGdiObject::Handle

TGdiObject::ShouldDelete

LOGBRUSH struct


TBrush::GetObject

See Also	TBrush

Syntax

bool GetObject(LOGBRUSH far& logBrush) const;

Description

Retrieves information about this brush object and places it in the given LOGBRUSH structure. Returns true if the call is successful; otherwise returns false.


See Also

TGdiObject::GetObject

LOGBRUSH struct


TBrush::operator HBRUSH()

TBrush

Syntax

operator HBRUSH() const;

Description

Typecasting operator. Converts this brush's Handle to type HBRUSH (the data type representing the handle to a physical brush).


TBrush::UnrealizeObject

TBrush

Syntax

bool UnrealizeObject();

Description

Directs the GDI to reset the origin of this brush the next time it is selected. Returns true if call is successful; otherwise returns false.


TButtonGadget Class

OWL Hierarchy	Inheritance

Header File

buttonga.h

Description

Derived from TGadget, TButtonGadgets represent buttons that you can click on or off. You can also apply attributes such as color, style, and shape (notched or unnotched) to your button gadgets.

In general, button gadgets are classified as either command or attribute buttons. Attribute buttons include radio buttons (which are considered exclusive), or check boxes (which are nonexclusive). The public data member, TType, enumerates these button types.

TButtonGadget contains several functions that let you change the style of a button. Use SetAntialiasEdges to turn antialiasing on and off, SetNotchCorners to control corner notching, and SetShadowStyle to change the style of the button shadow.

TButtonGadget objects respond to mouse events in the following manner:  when a mouse button is pressed, the button is pressed; when the mouse button is released, the button is released. Commands can be entered only when the mouse button is in the "up" state. When the mouse is pressed, TButtonGadget objects capture the mouse and reserve all mouse messages for the current window. When the mouse button is up, button gadgets release the capture for the current window. The public data member, TState, enumerates the three button states.

Type Definitions

enum TShadowStyle;

enum TState;

enum TType;

Public Constructor and Destructor

TButtonGadget(TResId bmpResId, int id, TType type = Command, bool enabled = false, TState state = Up, bool repeat = false);

~TButtonGadget();

Public Member Functions

void CommandEnable();

TState GetButtonState();

TType GetButtonType();

void SetAntialiasEdges(bool anti = true);

void SetButtonState(TState);

void SetNotchCorners(bool notchCorners = true);

void SetShadowStyle(TShadowStyle);

void SysColorChange();

Protected Data Members

bool AntialiasEdges;

TPoint BitmapOrigin;

TCelArray* CelArray;

bool NotchCorners;

bool Pressed;

bool Repeat;

TResId ResId;

TShadowStyle ShadowStyle;

TState State;

TType Type;

Protected Member Functions

virtual void Activate(TPoint& p);

virtual void BeginPressed(TPoint& p);

virtual void BuildCelArray();

virtual void CancelPressed(TPoint& p);

void GetDesiredSize(TSize& size);

virtual TDib* GetGlyphDib();

void Invalidate();

void LButtonDown(uint modKeys, TPoint& p);

void LButtonUp(uint modKeys, TPoint& p);

void MouseEnter(uint modKeys, TPoint& p);

void MouseLeave(uint modKeys, TPoint& p);

void MouseMove(uint modKeys, TPoint& p);

void Paint(TDC& dc);

virtual void ReleaseGlyphDib(TDib* glyph);

void SetBounds(TRect& r);


TButtonGadget::TShadowStyle enum

TButtonGadget

Syntax

enum TShadowStyle{SingleShadow = 1, DoubleShadow = 2};

Description

Enumerates button shadow styles--either single (1) or double (2) shadow borders.


TButtonGadget::TState enum

TButtonGadget

Syntax

enum TState{Up, Down, Indeterminate};

Description

TState enumerates the three button positions during which the button can be pressed: up (0), down (1), and an indeterminate state (2). A nonzero value indicates a highlighted button.


TButtonGadget::TType enum

TButtonGadget

Syntax

enum TType{Command, Exclusive, NonExclusive};

Description

Enumerates the types of button gadgets: a command button gadget, an exclusive button gadget, or a nonexclusive button gadget. An exclusive button is one that works in conjunction with other buttons such that one button is activated at a time.


TButtonGadget Public Constructor and Destructor

See Also	TButtonGadget

Syntax

TButtonGadget(TResId bmpResId, int id, TType type = Command, bool enabled = false, TState state = Up, bool repeat = false);

Destructor

~TButtonGadget();

Description

Constructs a TButtonGadget object using the specified bitmap ID, button gadget ID, and type, with enabled set to false and in a button-up state. The button isn't enabled - its initial state before command enabling occurs.

Destructor

Deconstructs a TButtonGadget object.


See Also

TButtonGadget::TState


TButtonGadget::CommandEnable

TButtonGadget

Syntax

void CommandEnable();

Description

Enables the button gadget to capture messages. Calls SendMessage to send a WM_COMMAND_ENABLE message to the gadget window's parent, passing a TCommandEnable: EvCommandEnable message for this button.


TButtonGadget::GetButtonState

See Also	TButtonGadget

Syntax

TState GetButtonState();

Description

Returns the state of the button. If 0, the button is up, if 1, the button is down, if 2, the state is indeterminate.


See Also

TButtonGadget::TState


TButtonGadget::GetButtonType

TButtonGadget

Syntax

TType GetButtonType();

Description

Returns the button type as 1 if the button is a command, 2 if exclusive, or 3 if nonexclusive.


TButtonGadget::SetAntialiasEdges

TButtonGadget

Syntax

SetAntialiasEdges(bool anti = true);

Description

Turns the antialiasing of the button bevels on or off. By default, antialiasing is on.


TButtonGadget::SetButtonState

See Also	TButtonGadget

Syntax

void SetButtonState(TState);

Description

Sets the state of the button. If the state has changed, the button is exclusive, and is in the down state, checks that the button is exclusive, sets State, and calls Invalidate to mark the changed area of the gadget for repainting.


See Also

TButtonGadget::TState


TButtonGadget::SetNotchCorners

See Also	TButtonGadget

Syntax

void SetNotchCorners(bool notchCorners = true);

Description

By default, SetNotchCorners implements notched corners for buttons. To repaint the frame of the button if the window has already been created, call InvalidateRect with the Bounds rectangle.


See Also

TButtonGadget::Invalidate

TGadget::InvalidateRect

TGadget::Paint


TButtonGadget::SetShadowStyle

TButtonGadget

Syntax

void SetShadowStyle(TShadowStyle);

Description

Sets the button style to a shadow style which, by default, is DoubleShadow. Sets the left and top borders to 2 and the right and bottom borders to ShadowStyle + 1.


TButtonGadget::SysColorChange

TButtonGadget

Syntax

void SysColorChange();

Description

SysColorChange responds to an EvSysColorChange message forwarded by the owning TGadgetWindow by setting the dither brush to zero. If a user-interface bitmap exists, SysColorchange deletes and rebuilds it to get the new button colors.


TButtonGadget::AntialiasEdges

TButtonGadget

Syntax

bool AntialiasEdges;

Description

Is true if antialiasing is turned on.


TButtonGadget::BitmapOrigin

TButtonGadget

Syntax

TPoint BitmapOrigin;

Description

Points to the x and y coordinates of the bitmap used for this button gadget.


TButtonGadget::NotchCorners

TButtonGadget

Syntax

bool NotchCorners;

Description

Initialized to 1, NotchCorners is 1 if the button gadget has notched corners or 0 if it doesn't have notched corners.


TButtonGadget::Pressed

See Also	TButtonGadget

Syntax

bool Pressed;

Description

Initialized to 1, Pressed is 1 if the button is released or 0 if it isn't released.


See Also

TButtonGadget::Activate

TButtonGadget::BeginPressed

TButtonGadget::CancelPressed


TButtonGadget::Repeat

TButtonGadget

Syntax

bool Repeat;

Description

Initialized to 1, Repeat stores the repeat count for keyboard events.


TButtonGadget::ResId

TButtonGadget

Syntax

TResId ResId;

Description

Holds the resource ID for this button gadget's bitmap.


TButtonGadget::ShadowStyle

TButtonGadget

Syntax

TShadowStyle ShadowStyle;

Description

Holds the shadow style for the button--1 for single and 2 for double.


TButtonGadget::State

TButtonGadget

Syntax

TState State;

Description

Holds the state of the button--either up, down, or indeterminate.


TButtonGadget::Type

TButtonGadget

Syntax

TType Type;

Description

Holds the type of the button--either command, exclusive, or nonexclusive.


TButtonGadget::CelArray

TButtonGadget

Syntax

TCelArray* CelArray;

Description

The array of cels used by this button gadget.


TButtonGadget::Activate

See Also	TButtonGadget

Syntax

virtual void Activate(TPoint& p);

Description

Invoked when the mouse is in the "up" state, Activate sets Pressed to false, changes the state for attribute buttons, and paints the button in its current state. To do this, it calls CancelPressed, posts a WM_COMMAND message to the gadget window's parent, and sends menu messages to the gadget window's parent.


See Also

TButtonGadget::Pressed


TButtonGadget::BeginPressed

See Also	TButtonGadget

Syntax

virtual void BeginPressed(TPoint& p);

Description

When the mouse button is pressed, Beginpressed sets Pressed to true, paints the pressed button, and sends menu messages to the gadget window's parent.


See Also

TButtonGadget::Pressed


TButtonGadget::BuildCelArray

See Also	TButtonGadget

Syntax

virtual void BuildCelArray();

Description

Builds a cel array using the resource bitmap as the base glyph. Any existing cel array should be deleted if a  replacement is built.


See Also

TCelArray


TButtonGadget::CancelPressed

See Also	TButtonGadget

Syntax

virtual void CancelPressed(TPoint& p);

Description

When the mouse button is released, CancelPressed sets Pressed to false, paints the button, and sends menu messages to the gadget window's parent.


See Also

TButtonGadget::Pressed


TButtonGadget::GetDesiredSize

TButtonGadget

Syntax

void GetDesiredSize(TSize& size);

Description

Stores the width and height (measured in pixels) of the button gadget in size. Calls TGadget's GetDesiredSize to calculate the relationship between one rectangle and another.


TButtonGadget::GetGlyphDib

TButtonGadget

Syntax

virtual TDib* GetGlyphDib();

Description

Supplies the glyphdib. You can override this function to get a different dib, or to change the attributes of the dib, such as the colors, and so on.


TButtonGadget::Invalidate

See Also	TButtonGadget

Syntax

void Invalidate();

Description

If a button is pressed or the state of the button is changed, Invalidate invalidates (marks for repainting) the changed area of the gadget. Invalidate only invalidates the area that changes. To repaint the entire gadget, call TGadget::InvalidateRect and pass the rectangle's boundaries.


See Also

TButtonGadget::TState

TGadget::InvalidateRect


TButtonGadget::LButtonDown

See Also	TButtonGadget

Syntax

void LButtonDown(uint modKeys, TPoint& p);

Description

Overrides TGadget member function and responds to a left mouse button click by calling BeginPressed.


See Also

TButtonGadget::BeginPressed


TButtonGadget::LButtonUp

See Also	TButtonGadget

Syntax

void LButtonUp(uint modKeys, TPoint& p);

Description

Overrides TGadget member functions and responds to a release of the left mouse button by calling Activate.


See Also

TButtonGadget::Activate


TButtonGadget::MouseEnter

TButtonGadget

Syntax

void MouseEnter(uint modKeys, TPoint& p);

Description

Called when the mouse enters the boundary of the button gadget. modKeys indicates the virtual key information and can be any combination of the following values: MK_CONTROL, MK_LBUTTON, MK_MBUTTON, MK_RBUTTON,  or MK_SHIFT. p indicates where the mouse entered the button gadget.


TButtonGadget::MouseLeave

TButtonGadget

Syntax

void MouseLeave(uint modKeys, TPoint& p);

Description

Called when the mouse leaves the boundary of the button gadget. modKeys indicates the virtual key information and can be any combination of the following values: MK_CONTROL, MK_LBUTTON, MK_MBUTTON, MK_RBUTTON,  or MK_SHIFT. p indicates the place where the mouse left the button gadget.


TButtonGadget::MouseMove

See Also	TButtonGadget

Syntax

void MouseMove(uint modKeys, TPoint& p);

Description

Calls TGadget::MouseMove in response to the mouse being dragged. If the mouse moves off the button, MouseMove calls CancelPressed. If the mouse moves back onto the button, MouseMove calls BeginPressed.


See Also

TButtonGadget::BeginPressed

TButtonGadget::CancelPressed


TButtonGadget::Paint

TButtonGadget

Syntax

void Paint(TDC& dc);

Description

Gets the width and height of the window frame (in pixels), calls GetImageSize to retrieve the size of the bitmap, and sets the inner rectangle to the specified dimensions. Calls TGadget::PaintBorder to perform the actual painting of the border of the control. Before painting the control, Paint determines whether the corners of the control are notched, and then calls GetSysColor to see if highlighting or shadow colors are used. Paint assumes the border style is plain. Then, Paint draws the top, left, right, and bottom of the control, adjusts the position of the bitmap, and finishes drawing the control using the specified embossing, fading, and dithering.


TButtonGadget::ReleaseGlyphDib

TButtonGadget

Syntax

virtual void ReleaseGlyphDib(TDib* glyph);

Description

Releases the glyph dib depending on how it was obtained by GetGlyphDib.


TButtonGadget::SetBounds

See Also	TButtonGadget

Syntax

void SetBounds(TRect& r);

Description

Gets the size of the bitmap, calls TGadget::SetBounds to set the boundary of the rectangle, and centers the bitmap within the button's rectangle.


See Also

TGadget::SetBounds


TButton Class

OWL Hierarchy	Inheritance

Header File

button.h

Description

TButton is an interface class that represents a pushbutton interface element. You must use a TButton to create a button control in a parent TWindow object. You can also use a TButton to facilitate communication between your application and the button controls of a TDialog object. This class is streamable.

There are two types of pushbuttons: regular and default. Regular buttons have a thin border. Default buttons (which represent the default action of the window) have a thick border.

Public Data Members

bool IsDefPB;

Public Constructors

TButton(Window* parent, int Id, const char far* text, int X, int Y, int W, int H, bool isDefault = false, TModule* module = 0);

TButton(TWindow* parent, int resourceID, TModule* module = 0);

Protected Data Member

bool IsCurrentDefPB;

Protected Member Functions

LRESULT BMSetStyle(WPARAM, LPARAM);

uint EvGetDlgCode(MSG far*);

char far* GetClassName();

void SetupWindow();

Response Table Entries

EV_ macros and member functions


TButton::IsDefPB

TButton

Syntax

bool IsDefPB;

Description

Indicates whether the button is to be considered the default push button. Used for owner-draw buttons, IsDefPB is set by a TButton constructor based on BS_DEFPUSHBUTTON style setting.


TButton Public Constructors

See Also	TButton

Syntax 1

TButton(Window *parent, int Id, const char far* text, int X, int Y, int W, int H, bool isDefault = false, TModule* module = 0);

Description

Constructs a button object with the supplied parent window (parent), control ID (Id), associated text (text), position (X,Y) relative to the origin of the parent window's client area, width (W), and height (H). If IsDefault is true, the constructor adds BS_DEFPUSHBUTTON to the default styles set for the TButton (in Attr.Style). Otherwise, it adds BS_PUSHBUTTON.

Syntax 2

TButton(TWindow* parent, int resourceID, TModule* module = 0);

Description

Constructs a TButton object to be associated with a button control of a TDialog object. Calls DisableTransfer to exclude the button from the transfer mechanism because there is no data to be transferred.

The resId parameter must correspond to a button resource that you define.


See Also

TControl::TControl


TButton::IsCurrentDefPB

TButton

Syntax

bool IsCurrentDefPB;

Description

Indicates whether the current button is the default push button.


TButton::BMSetStyle

TButton

Syntax

LRESULT BMSetStyle(WPARAM, LPARAM);

Description

Because a button can't have both owner-drawn and push button styles, BMSetStyle keeps track of the style if the button is owner-drawn and the system tries to set the style to BS_DEFPUSHBUTTON. BMSetStyle sets IsCurrentDefPB to true if the button style is BS_DEFPUSHBUTTON.


TButton::EvGetDlgCode

See Also	TButton

Syntax

uint EvGetDlgCode(MSG far*);

Description

Responds to WM_GETDLGCODE messages that are sent to a dialog box associated with a control. EvGetDlgCode allows the dialog manager to intercept a message that would normally go to a control and then ask the control if it wants to process this message. If not, the dialog manager processes the message. The msg parameter indicates the kind of message (for example, a control, command, or button message) sent to the dialog box manager.

EvGetDlgCode returns a code that indicates how the button is to be treated. If this is the currently used push button, EvGetDlgCode  returns either DLGC_DEFPUSHBUTTON or DLGC_UNDEFPUSHBUTTON.


See Also

DLGC_xxxx Dialog Control Message Constants


TButton::GetClassName

TButton

Syntax

char far* GetClassName();

Description

Overrides TWindow's GetClassName function. If Borland Windows Custom Controls (BWCC) is enabled, returns the name of TButton's registration class, "BUTTON_CLASS". If BWCC isn't enabled, returns the name "BUTTON".


TButton::SetupWindow

TButton

Syntax

void SetupWindow();

Description

Overrides TWindow's SetupWindow function. If the button is the default push button and an owner-drawn button, SetupWindow sends a DM_SETDEFID message to the parent window.


TButton Response Table Entries
TButton::Response Table Entries

TButton

Response table entry	Member function

EV_WM_GETDLGCODE	EVGetDlgCode

EV_MESSAGE (BM_SETSTYLE, BMSetStyle)	BMSetStyle


TCelArray Class

OWL Hierarchy

Header File

celarray.h

Description

TCelArray is a horizontal array of cels (a unit of animation) created by slicing a portion of or an entire bitmap into evenly sized shapes. Gadgets such as buttons can use a TCelArray to save resource space. TCelArray's functions let you control the dimensions of each cel and determine if the cel can delete the bitmap.

Public Constructors and Destructor

TCelArray(TBitmap* bmp, int numCels, TSize celSize = 0, TPoint Offset = 0, TAutoDelete = AutoDelete);

TCelArray(TDib& dib, int numCels);

TCelArray(const TCelArray& src);

virtual ~TCelArray();

Public Member Functions

TSize CelSize() const;

TPoint CelOffset(int cel);

TRect CelRect(int cel) const;

int NumCels() const;

TPoint Offset() const;

TRect operator [](int cel) const;

TCelArray& operator =(const TCelArray&);

operator TBitmap&();

void SetCelSize(TSize size);

void SetOffset(TPoint offs);

void SetNumCels(int numCels);

Protected Data Members

TBitmap* Bitmap;

TSize CSize;

TPoint Offs;

int NCels;

bool ShouldDelete;


TCelArray Public Constructors and Destructor

TCelArray

Syntax 1

TCelArray(TBitmap* bmp, int numCels, TSize celSize = 0, TPoint Offset = 0, TAutoDelete = AutoDelete);

Description

Constructs a TCelArray from a bitmap by slicing the bitmap into a horizontal array of cels of a specified size. If autoDelete is true, TCelArray can automatically delete the bitmap. The ShouldDelete data member defaults to true, ensuring that the handle will be deleted when the bitmap is destroyed.

Syntax 2

TCelArray(TDib& dib, int numCels);

Description

Constructs a TCelArray from a device independent bitmap (DIB) by slicing the DIB into a horizontal array of evenly sized cels.

Syntax 3

TCelArray(const TCelArray& src);

Description

Constructs a TCelArray as a copy of an existing one. If the original TCelArray owned its bitmap, the constructor copies this bitmap; otherwise, it keeps a reference to the bitmap.

Destructor

virtual ~TCelArray();

Description

If ShouldDelete is true (the default value), the bitmap is deleted. If ShouldDelete is false, no action is taken.


TCelArray::CelSize

TCelArray

Syntax

TSize CelSize() const;

Description

Returns the size in pixels of each cell.


TCelArray::CelOffset

TCelArray

Syntax

TPoint CelOffset(int cels);

Description

Returns the position of the upper left corner of a given cel relative to the upper left corner of the bitmap.


TCelArray::CelRect

TCelArray

Syntax

TRect CelRect(int cel) const;

Description

Returns the upper left and lower right corner of a given cell relative to the upper left corner of the bitmap.


TCelArray::NumCels

TCelArray

Syntax

int NumCels() const;

Description

Returns the number of cels in the array.


TCelArray::Offset

TCelArray

Syntax

TPoint Offset() const;

Description

Returns the offset of the entire CelArray.


TCelArray::operator [ ]

TCelArray

Syntax

TRect operator [](int cel) const;

Description

Returns CelRect.


TCelArray::operator =

TCelArray

Syntax

TCelArray& operator =(const TCelArray&);

Description

Returns TCelArray.


TCelArray::operator TBitmap&

TCelArray

Syntax

operator TBitmap&();

Description

Returns a reference to the bitmap.


TCelArray::SetCelSize

TCelArray

Syntax

void SetCelSize(TSize size);

Description

Sets the size of each cel in the array.


TCelArray::SetOffset

TCelArray

Syntax

void SetOffset(TPoint offs);

Description

Sets the offset for the cels in the array.


TCelArray::SetNumCels

TCelArray

Syntax

void SetNumCels(int numCels);

Description

Sets the number of cels in the array.


TCelArray::Bitmap

TCelArray

Syntax

TBitmap* Bitmap;

Description

Points to the bitmap.


TCelArray::CSize

TCelArray

Syntax

TSize CSize;

Description

The size of a cell in the array.


TCelArray::Offs

TCelArray

Syntax

TPoint Offs;

Description

Holds the offset of the upper left corner of the cel array from the upper left corner of the bitmap.


TCelArray::NCels

TCelArray

Syntax

int NCels;

Description

The number of cells in the cel array.


TCelArray::ShouldDelete

TCelArray

Syntax

bool ShouldDelete;

Description

Is true if the Destructor needs to delete the bitmap associated with the cel array.


TCharSet Class

OWL Hierarchy	Inheritance

Header File

bitset.h

Description

Derived from TBitSet, TCharSet sets and clears bytes for a group of characters. You can use this class to set or clear bits in a group of characters, such as the capital letters from "A" through "Z" or the lowercase letters from "a" through "z". The class TBitSet performs similar operations for a group of bits.

Public Constructors

TCharSet();

TCharSet(const TCharSet&);

TCharSet(const char far* str);

Public Member Function

int operator !=(const TBitSet& bs1, const TBitSet& bs2);


TCharSet Public Constructors

TCharSet

Syntax 1

TCharSet();

Description

Constructs a TCharSet object.

Syntax 2

TCharSet(const TCharSet&);

Description

Copy constructor for a TCharSet object.

Syntax 3

TCharSet(const char far* str);

Description

Constructs a string of characters.


TCharSet::operator !=

TCharSet

Syntax

int operator !=(const TBitSet& bs1, const TBitSet& bs2);

Description

ORs all the bits in the copied string and returns a reference to the copied TCharSet object.


TCheckBox Class

OWL Hierarchy	Inheritance

Header File

checkbox.h

Description

TCheckBox is a streamable interface class that represents a check box control. Use TCheckBox to create a check box control in a parent window. You can also use TCheckBox objects to more easily manipulate check boxes you created in a dialog box resource.

Two-state check boxes can be checked or unchecked; three-state check boxes have an additional grayed state. TCheckBox member functions let you easily control the check box's state. A check box can be in a group box (a TGroupBox object) that groups related controls.

Public Data Member

TGroupBox *Group;

Public Constructors

TCheckBox(TWindow* parent, int Id, const char far* title, int x, int y, int w, int h, TGroupBox* group = 0, TModule* module = 0);

TCheckBox(TWindow* parent, int resourceId, TGroupBox* group = 0, TModule* module = 0);

Public Member Functions

void Check();

uint GetCheck() const;

uint GetState() const;

void SetCheck(uint check);

void SetState(uint state);

void SetStyle(uint style, bool redraw);

void Toggle();

uint Transfer(void* buffer, TTransferDirection direction);

void Uncheck();

Protected Member Functions

void BNClicked();

uint EvGetDlgCode(MSG far* msg);

char far* GetClassName();

Response Table Entries

EV_ macros and member functions


TCheckBox::Group

TCheckBox

Syntax

TGroupBox* Group;

Description

If the check box belongs to a group box (a TGroupBox object), Group points to that object. If the check box is not part of a group, Group is zero.


TCheckBox Public Constructors

TCheckBox

Syntax 1

TCheckBox(TWindow* parent, int Id, const char far* title, int x, int y, int w, int h, TGroupBox* group = 0, TModule* module = 0);

Description

Constructs a check box object with the specified parent window (parent), control ID (Id), associated text (title), position relative to the origin of the parent window's client area (x, y), width (w), height (h), associated group box (group), and owning module (module). Invokes the TButton constructor with similar parameters. Sets the check box's style to WS_CHILD | WS_VISIBLE | WS_TABSTOP | BS_AUTOCHECKBOX.

Form 2

TCheckBox(TWindow* parent, int resourceId, TGroupBox* group = 0, TModule* module = 0);

Description

Constructs an associated TCheckBox object for the check box control with a resource ID of resourceId in the parent dialog box. Sets Group to group then enables the data transfer mechanism by calling TWindow::EnableTransfer.


TCheckBox::Check

See Also	TCheckBox

Syntax

void Check();

Description

Forces the check box to be checked by calling SetCheck with the value BF_CHECKED. Notifies the associated group box, if there is one, that the state was changed.


See Also

TCheckBox::GetCheck

TCheckBox::Toggle

TCheckBox::Uncheck

TGroupBox::SelectionChanged


TCheckBox::GetCheck

See Also	TCheckBox

Syntax

uint GetCheck() const;

Description

Returns the state of the check box.

TCheckBox Check States

Check box state	Return value

Checked	BF_CHECKED

Unchecked	BF_UNCHECKED

Grayed	BF_GRAYED


See Also

TCheckBox::SetCheck


TCheckBox::GetState

See Also	TCheckBox

Syntax

uint GetState() const;

Description

Returns the check, focus, and highlight state of the check box.


See Also

TCheckBox::SetState


TCheckBox::SetCheck

See Also	TCheckBox

Syntax

void SetCheck(uint check);

Description

Forces the check box into the state specified by check.


See Also

TCheckBox::GetCheck


TCheckBox::SetState

See Also	TCheckBox

Syntax

void SetState(uint state);

Description

Sets the check, focus, and highlight state of the check box.


See Also

TCheckBox::GetState


TCheckBox::SetStyle

TCheckBox

Syntax

void SetStyle(uint style, bool redraw);

Description

Changes the style of the check box.


TCheckBox::Toggle

See Also	TCheckBox

Syntax

void Toggle();

Description

Toggles the check box between checked and unchecked if it is a two-state check box; toggles it between checked, unchecked, and gray if it is a three-state check box.


See Also

TCheckBox::SetCheck


TCheckBox::Transfer

TCheckBox

Syntax

uint Transfer(void* buffer, TTransferDirection direction);

Description

Overrides TWindow::Transfer. Transfers the check state of the check box to or from buffer, using the values specified in the table in GetCheck. If direction is tdGetDate, the check box state is transferred into the buffer. If direction is tdSetData, the check box state is changed to the settings in the transfer buffer.

Transfer returns the size of the transfer data in bytes. To get the size without actually transferring the check box, use tdSizeData as the direction argument.


TCheckBox::Uncheck

See Also	TCheckBox

Syntax

void Uncheck();

Description

Forces the check box to be unchecked by calling SetCheck with a value of BF_UNCHECKED. Notifies the associated group box, if there is one, that the state has changed.


See Also

TCheckBox::Check

TCheckBox::SetCheck

TCheckBox::Toggle


TCheckBox::BNClicked

TCheckBox

Syntax

void BNClicked();

Description

Responds to notification message BN_CLICKED, indicating that the user clicked the check box. If Group isn't 0, BNClicked calls the group box's SelectionChanged member function to notify the group box that the state has changed.


TCheckBox::EvGetDlgCode

See Also	TCheckBox

Syntax

uint EvGetDlgCode(MSG far* msg);

Description

Overrides TButton's response to the WM_GETDLGCODE message, an input procedure associated with a control that is not a check box, by calling DefaultProcessing. The msg parameter indicates the kind of message sent to the dialog box manager, such as a control message, a command message, or a check box message.

EvGetDlgCode returns a code that indicates how the check box is to be treated.


See Also

TButton::EvGetDlgCode

TWindow::DefaultProcessing

DLGC_xxxxdialogcontrolmessageconstants


TCheckBox::GetClassName

TCheckBox

Syntax

char far* GetClassName();

Description

If BWCC is enabled, returns CHECK_CLASS. If BWCC is not enabled, returns "BUTTON."


TCheckBox Response Table Entries

TCheckBox

Response table entry	Member function

EV_NOTIFY_AT_CHILD (BN_CLICKED, BNClicked)	BNClicked

EV_WM_GETDLGCODE	EVGetDlgCode


TChooseColorDialog Class

OWL Hierarchy	Inheritance

Header File

chooseco.h

Description

TChooseColorDialog objects represent modal dialog box interface elements that allow color selection and custom color adjustment. TChooseColorDialog can be made to appear modeless to the user by creating the dialog's parent as an invisible pop-up window and making the pop-up window a child of the main application window. TChooseColorDialog uses the TChooseColor::TData struct to initialize the dialog box with the user's color selection.

Public Constructor

TChooseColorDialog(TWindow* parent, TData& data, TResId templateID = 0, const char far* title = 0, TModule* module = 0);

Public Member Function

void SetRGBColor(TColor color);

Public Data Members

CHOOSECOLOR cc;

TData& Data;

static uint SetRGBMsgId;

Protected Member Functions

bool DialogFunction(uint message, WPARAM, LPARAM);

int DoExecute();

LPARAM EvSetRGBColor(WPARAM, LPARAM);

Response Table Entries

The TChooseColorDialog response table has no entries.

Class

TData


 TChooseColorDialog Public Constructor

See Also	TChooseColorDialog

Syntax

TChooseColorDialog(TWindow* parent, TData& data, TResId templateID = 0, const char far* title = 0, TModule* module = 0);

Description

Constructs a dialog box with specified parent window, data, resource identifier, window caption, and module ID. Sets the attributes of the dialog box based on info in the TChooseColor::TData  structure.


See Also

TChooseColorDialog::TData


TChooseColorDialog::SetRGBColor

TChooseColorDialog

Syntax

void SetRGBColor(TColor color);

Description

Sets the current RGB color for the open dialog box by sending a SetRGBMsgId. You can use SetRGBColor to send a message to change the current color selection.


TChooseColorDialog::cc

See Also	TChooseColorDialog

Syntax

CHOOSECOLOR cc;

Description

Stores the length of the TChooseColorDialog structure, the window that owns the dialog box, and the data block that contains the dialog template. It also points to an array of 16 RGB values for the custom color boxes in the dialog box, and specifies the dialog-box initialization flags.


See Also

TChooseColorDialog::TData


TChooseColorDialog::Data

See Also	TChooseColorDialog

Syntax

TData& Data;

Description

Data is a reference to the TData object passed in the constructor.


See Also

TChooseColorDialog::TData


TChooseColorDialog::SetRGBMsgId

TChooseColorDialog

Syntax

static uint SetRGBMsgId;

Description

Contains the ID of the registered message sent by SetRGBColor.


TChooseColorDialog::DialogFunction

See Also	TChooseColorDialog

Syntax

bool DialogFunction(uint message, WPARAM, LPARAM);

Description

Returns true if a message is handled.


See Also

TDialog::DialogFunction


TChooseColorDialog::DoExecute

TChooseColorDialog

Syntax

int DoExecute();

Description

If no error occurs, DoExecute copies flags and colors into Data and returns zero. If an error occurs, DoExecute returns the IDCANCEL with Data.Error set to the value returned from CommDlgExtendedError.


TChooseColorDialog::EvSetRGBColor

TChooseColorDialog

Syntax

LPARAM EvSetRGBColor(WPARAM, LPARAM);

Description

Responds to the message sent by SetRGBColor by forwarding the to the original class. This event handler is not in the response table.


TChooseColorDialog Response Table Entries

TChooseColorDialog

Description

The TChooseColorDialog response table has no entries.


TChooseColorDialog TData Class
TChooseColorDialog::TData Class

TChooseColorDialog

Header File

chooseco.h

Description

Defines information necessary to initialize the dialog box with the user's color selection.

Public Data Members

TColor Color;

TColor* CustColors;

uint32 Error;

uint32 Flags;


TChooseColorDialog::TData::Color

TChooseColorDialog::TData

Syntax

TColor Color;

Description

Specifies the color that is initially selected when the dialog box is created. Contains the user's color selection when the dialog box is closed.


TChooseColorDialog::TData::CustColors

TChooseColorDialog::TData

Syntax

TColor* CustColors;

Description

Points to an array of 16 colors.


TChooseColorDialog::TData::Error

TChooseColorDialog::TData

Syntax

uint32 Error;

Description

 If the dialog box is successfully executed,  Error  is 0. Otherwise, it contains one of the following codes:

Constant	Meaning

CDERR_DIALOGFAILURE	Failed to create a dialog box.

CDERR_FINDRESFAILURE	Failed to find a specified resource.

CDERR_LOADRESFAILURE	Failed to load a specified resource.

CDERR_LOCKRESOURCEFAILURE	Failed to lock a specified resource.

CDERR_LOADSTRFAILURE	Failed to load a specified string.


TChooseColorDialog::TData::Flags

See Also	TChooseColorDialog::TData

Syntax

uint32 Flags;

Description

Flags can be a combination of the following values that control the appearance and functionality of the dialog box:

Constant	Meaning

CC_FULLOPEN	Causes the entire dialog box to appear when the dialog box is created.

CC_PREVENTFULLOPEN	Disables the "Define Custom Colors" push button.

CC_RGBINIT	Causes the dialog box to use the color specified in rgbResult as the initial color selection.

CC_SHOWHELP	Causes the dialog box to show the Help push button.


See Also

TChooseColorDialog::Data


TChooseFontDialog Class

OWL Hierarchy	Inheritance

Header File

choosefo.h

Description

A TChooseFontDialog represents modal dialog-box interface elements that create a system-defined dialog box from which the user can select a font, a font style (such as bold or italic), a point size, an effect (such as strikeout or underline), and a color. TChooseFontDialog can be made to appear modeless by creating the dialog's parent as an invisible pop-up window and making the pop-up window a child of the main application window. TChooseFontDialog  uses the TChooseFontDialog::TData  structure to initialize the dialog box with the user-selected font styles.

Public Constructor

TChooseFontDialog(TWindow* parent, TData& data, TResID templateID = 0, const char far* title = 0, TModule* module = 0);

Protected Data Members

CHOOSEFONT cf;

TData& Data;

Protected member functions

void CmFontApply();

bool DialogFunction(uint message, WPARAM, LPARAM);

int DoExecute();

Response Table Entries

The TChooseFontDialog response table has no entries.

Class

TData


TChooseFontDialog Public Constructors
 TChooseFontDialog Public Constructor

See Also	TChooseFontDialog

Syntax

TChooseFontDialog(TWindow* parent, TData& data, TResID templateID = 0, const char far* title = 0, TModule* module = 0);

Description

Constructs a dialog box with specified data, parent window, resource identifier, window caption, and module ID. Sets the attributes of the dialog box based on the font information in the TChooseFontDialog::TData  structure.


See Also

TChooseFontDialog::TData


TChooseFontDialog::cf

See Also	TChooseFontDialog

Syntax

CHOOSEFONT cf;

Description

Contains font attributes. cf is initialized using fields in the TChooseFontDialog::TData structure. It stores the length of the structure, the window that owns the dialog box and the data block that contains the dialog template. It also specifies the dialog-box initialization flags.


See Also

TChooseFontDialog::TData


TChooseFontDialog::Data

See Also	TChooseFontDialog

Syntax

TData& Data;

Description

Data is a reference to the TData object passed in the constructor.


See Also

TChooseFontDialog::TData


TChooseFontDialog::CmFontApply

TChooseFontDialog

Syntax

void CmFontApply();

Description

Default handler for the third push button (the apply button) in the dialog box.


TChooseFontDialog::DialogFunction

See Also	TChooseFontDialog

Syntax

bool DialogFunction(uint message, WPARAM, LPARAM);

Description

Returns true if a dialog box message is handled.


See Also

TDialog::DialogFunction


TChooseFontDialog::DoExecute

See Also	TChooseFontDialog

Syntax

int DoExecute();

Description

If no error occurs, DoExecute copies the flag values and font information into Ddata, and returns IDOK or IDCANCEL. If an error occurs, DoExecute returns an error code from TChooseFontDialog::TData structure's  Error  data member.


See Also

TChooseFontDialog::TData


TChooseFontDialog Response Table Entries

TChooseFontDialog

The TChooseFontDialog response table contains no entries.


TChooseFontDialog::TData Class

TChooseFontDialog

Header File

choosefo.h

Defines information necessary to initialize the dialog box with the user's font selection.

Public Data Members

TColor Color;

HDC DC;

uint32 Error;

uint32 Flags;

uint16 FontType;

LOGFONT LogFont;

int PointSize;

int SizeMax;

int SizeMin;

char far* Style;


TChooseFontDialog::TData::Color

TChooseFontDialog::TData

Syntax

TColor Color;

Description

Indicates the font color that is initially selected when the dialog box is created; contains the user's font color selection when the dialog box is closed.


TChooseFontDialog::TData::DC

TChooseFontDialog::TData

Syntax

HDC DC;

Description

Handle to the device context from which fonts are obtained.


TChooseFontDialog::TData::Error

TChooseFontDialog::TData

Syntax

uint32 Error;

Description

If the dialog box is successfully executed, Error  returns 0. Otherwise, it contains one of the following codes:

Constant	Meaning

CDERR_DIALOGFAILURE	Failed to create a dialog box.

CDERR_FINDRESFAILURE	Failed to find a specified resource.

CDERR_LOCKRESOURCEFAILURE	Failed to lock a specified resource.

CDERR_LOADRESFAILURE	Failed to load a specified resource.

CDERR_LOADSTRFAILURE	Failed to load a specified string.

CFERR_MAXLESSTHANMIN	The size specified in SizeMax is less than the size in SizeMin.

CFERR_NOFONTS	No fonts exist.


TChooseFontDialog::TData::Flags

TChooseFontDialog::TData

Syntax

uint32 Flags;

Description

Flags can be a combination of the following constants that control the appearance and functionality of the dialog box:

Constant	Meaning

CF_APPLY	Enables the display and use of the Apply button.

CF_ANSIONLY	Specifies that the ChooseFontDialog structure allows only the selection of fonts that use the ANSI character set.

CF_BOTH	Causes the dialog box to list both the available printer and screen fonts.

CF_EFFECTS	Enables strikeout, underline, and color effects.

CF_FIXEDPITCHONLY	Enables fixed-pitch fonts only.

CF_FORCEFONTEXIST	Indicates an error if the user selects a nonexistent font or style.

CF_INITTOLOGFONTSTRUCT	Uses the LOGFONT structure at which LogFont points to initialize the dialog controls.

CF_LIMITSIZE	Limits font selection to those between SizeMin and SizeMax.

CF_NOSIMULATIONS	Does not allow GDI font simulations.

CF_PRINTERFONTS	Causes the dialog box to list only the fonts supported by the printer that is associated with the device context.

CF_SCALABLEONLY	Allows only the selection of scalable fonts.

CF_SCREENFONTS	Causes the dialog box to list only the system-supported screen fonts.

CF_SHOWHELP	Causes the dialog box to show the Help button.

CF_TTONLY	Enumerates and allows the selection of TrueType fonts only.

CF_USESTYLE	Specifies that Style points to a buffer containing the style attributes used to initialize the selection of font styles.

CF_WYSIWYG	Allows only the selection of fonts available on both the printer and the screen.


TChooseFontDialog::TData::LogFont

TChooseFontDialog::TData

Syntax

LOGFONT LogFont;

Description

Attributes of the font.


TChooseFontDialog::TData::PointSize

TChooseFontDialog::TData

Syntax

int PointSize;

Description

Point size of the font.


TChooseFontDialog::TData::Style

TChooseFontDialog::TData

Syntax

char far* Style;

Description

Style of the font such as bold, italic, underline, or strikeout.


TChooseFontDialog::TData::FontType

TChooseFontDialog::TData

Syntax

uint16 FontType;

Description

Font type or name.


TChooseFontDialog::TData::SizeMax

TChooseFontDialog::TData

Syntax

int SizeMax;

Description

Maximum size of the font.


TChooseFontDialog::TData::SizeMin

TChooseFontDialog::TData

Syntax

int SizeMin;

Description

Minimum size of the font.


TClientDC Class

See Also	OWL Hierarchy	Inheritance

Header File

dc.h

Description

A DC class derived from TWindowDC, TClientDC provides access to the client area owned by a window.

Public Constructor

TClientDC(HWND wnd);


See Also

TOleClientDC


TClientDC Public Constructor

See Also	TClientDC

Syntax

TClientDC(HWND wnd);

Description

Creates a TClientDC object with the given owned window. The data member Wnd is set to wnd.


See Also

TWindowDC::Wnd

TDC::TDC


TClipboard Class

OWL Hierarchy	Inheritance

Header File

clipboar.h

Description

TClipboard encapsulates and manipulates clipboard data. You can open, close, empty, and paste data in a variety of data formats between the Clipboard and the open window.  An object on the clipboard can exist in a variety of clipboard formats, which range from bitmaps to text.

Usually, the window is in charge of manipulating clipboard interactions between the window and the clipboard. It does this by responding to messages sent between the clipboard owner and the application. The following ObjectWindows event-handling functions encapsulate these clipboard messages:

EvRenderFormat - Responds to a WM_RENDERFORMAT message sent to the clipboard owner if a specific clipboard format that an application has requested hasn't been rendered. After the clipboard owner renders the data in the requested format, it calls SetClipboardData to place the data on the clipboard.

EvRenderAllFormats - Responds to a message sent to the clipboard owner if the clipboard owner has delayed rendering a clipboard format.  After the clipboard owner renders data in all of possible formats, it calls SetClipboardData.

The following example tests to see If there is a palette on the clipboard. If one exists, TClipboard retrieves the palette, realizes it, and then closes the clipboard.

  if (clipboard.IsClipboardFormatAvailable(CF_PALETTE)) {

    newPal = new TPalette(TPalette(clipboard));  // make a copy

    UpdatePalette(true);

  }

  // Try DIB format first

  if (clipboard.IsClipboardFormatAvailable(CF_DIB)) {

    newDib = new TDib(TDib(clipboard));        // make a copy

    newBitmap = new TBitmap(*newDib, newPal);  // newPal==0 is OK

  // try metafile Second

  //

  } else if (clipboard.IsClipboardFormatAvailable(CF_METAFILEPICT)) {

    if (!newPal)

      newPal = new TPalette((HPALETTE)GetStockObject(DEFAULT_PALETTE));

    newBitmap = new TBitmap(TMetaFilePict(clipboard), *newPal,

                            GetClientRect().Size());

...

  // Gets a bitmap , keeps it, and sets up data on the clipboard.

  //

  delete Bitmap;

  Bitmap = newBitmap;

  if (!newDib)

    newDib = new TDib(*newBitmap, newPal);

#endif

  delete Dib;

  Dib = newDib;

  delete Palette;

  Palette = newPal ? newPal : new TPalette(*newDib);

  Palette->GetObject(Colors);

  PixelWidth  = Dib->Width();

  PixelHeight = Dib->Height();

  AdjustScroller();

  SetCaption("(Clipboard)");

  clipboard.CloseClipboard();

Public Destructor

~TClipboard();

Public Data Members

static const char* DefaultProtocol;

Public Member Functions

void CloseClipboard()

int CountClipboardFormats() const;

bool EmptyClipboard();

static TClipboard& GetClipboard()

HANDLE GetClipboardData(uint format) const;

int GetClipboardFormatName(uint format, char far* formatName, int maxCount) const;

HWND GetClipboardOwner() const;

HWND GetClipboardViewer() const;

HWND GetOpenClipboardWindow() const;

int GetPriorityClipboardFormat(uint FAR * priorityList, int count) const;

bool IsClipboardFormatAvailable(uint format) const;

bool OpenClipboard(HWND Wnd);

operator bool() const;

bool QueryCreate(const char far* protocol = DefaultProtocol, OLEOPT_RENDER renderopt = olerender_draw, OLECLIPFORMAT format = 0);

bool QueryLink(const char far* protocol = DefaultProtocol, OLEOPT_RENDER renderopt = olerender_draw, OLECLIPFORMAT format = 0);

uint RegisterClipboardFormat(const char far* formatName) const;

HANDLE SetClipboardData(uint format, HANDLE handle);

HWND SetClipboardViewer(HWND Wnd) const;

Protected Data Members

bool IsOpen;

static TClipboard TheClipboard;

Protected Constructor

TClipboard();


TClipboard Public Destructor

TClipboard

Syntax

~TClipboard();

Description

Destroys the TClipboard object.


TClipboard::DefaultProtocol

See Also	TClipboard

Syntax

static const char* DefaultProtocol;

Description

Points to a string that specifies the name of the protocol the client needs. The default protocol is "StdFileEditing," which is the name of the object linking and embedding protocol.


See Also

TClipboard::QueryCreate


TClipboard::CloseClipboard

See Also	TClipboard

Syntax

void CloseClipboard()

Description

If the Clipboard is closed (IsOpen is false), closes the Clipboard. Closing the Clipboard allows other applications to access the Clipboard.


See Also

TClipboard::OpenClipboard


TClipboard::CountClipboardFormats

See Also	TClipboard

Syntax

int CountClipboardFormats() const;

Description

Returns a count of the number of types of data formats the Clipboard can use.


See Also

TClipboard::RegisterClipboardFormat


TClipboard::EmptyClipboard

TClipboard

Syntax

bool EmptyClipboard();

Description

Clears the Clipboard and frees any handles to the Clipboard's data. Returns true if the Clipboard is empty, or false if an error occurs.


TClipboard::GetClipboard

TClipboard

Syntax

static TClipboard& GetClipboard()

Description

Returns a reference to the TClipboard object.


TClipboard::GetClipboardData

See Also	TClipboard

Syntax

HANDLE GetClipboardData(uint format) const;

Description

Retrieves data from the Clipboard in the format specified by format.The following formats are supported:

Value	Meaning

CF_BITMAP	Data is in a bitmap format

CF_DIB	Data is memory

CF_DIF	Data is in a Data Interchange Format (DIF).

CF_DSPMETAFILEPICT	Data is in a metafile format.

CF_DSPTEXT	Data is in a text format.

CF_METAFILEPICT	Data is in a metafile structure.

CF_OEMTEXT	Data is an array of text characters in OEM character set.

CF_OWNERDISPLAT	Data is in a special format that the application must display.

CF_PALETTE	Data is in a color palette format.

CF_PENDATA	Data is used for pen format.

CF_RIFF	Data is in Resource Interchange File Format (RIFF).

CF_SYLK	Data is in symbolic Link format (SYLK).

CF_TEXT	Data is stored as an array of text characters.

CF_TIFF	Data is in Tag Image File Format (TIFF).

CF_WAVE	Data is in a sound wave format.


See Also

TClipboard::SetClipboardData


TClipboard::GetClipboardFormatName

See Also	TClipboard

Syntax

int GetClipboardFormatName(uint format, char far* formatName, int maxCount) const;

Description

Retrieves the name of the registered format specified by format and copies the format to the buffer pointed to by formatName. maxCount specifies the maximum length of the name of the format. If the name is longer than maxCount, it is truncated.


See Also

TClipboard::CountClipboardFormats


TClipboard::GetClipboardOwner

TClipboard

Syntax

HWND GetClipboardOwner() const;

Description

Retrieves the handle of the window that currently owns the Clipboard, otherwise returns NULL.


TClipboard::GetClipboardViewer

See Also	TClipboard

Syntax

HWND GetClipboardViewer() const;

Description

Retrieves the handle of the first window in the Clipboard-view chain. Returns NULL if there is no viewer.


See Also

TClipboard::SetClipboardViewer


TClipboard::GetOpenClipboardWindow

TClipboard

Syntax

HWND GetOpenClipboardWindow() const;

Description

Retrieves the handle of the window that currently has the Clipboard open. If the Clipboard is not open, the return value is false. Once the Clipboard is opened, applications cannot modify the data.


TClipboard::GetPriorityClipboardFormat

See Also	TClipboard

Syntax

int GetPriorityClipboardFormat(uint FAR * priorityList, int count) const;

Description

Returns the first Clipboard format in a list. priorityList points to an array that contains a list of the Clipboard formats arranged in order of priority. See GetClipboardData for the clipboard formats.


See Also

TClipboard::GetClipboardData


TClipboard::IsClipboardFormatAvailable

See Also	TClipboard

Syntax

bool IsClipboardFormatAvailable(uint format) const;

Description

Indicates if the format specified in format exists for use in the Clipboard. See GetClipBoardData for a description of clipboard data formats.

The following code tests if the clipboard can support the specified formats:

void

TBmpViewWindow::CePaste(TCommandEnabler& ce)

{

  TClipboard& clipboard = OpenClipboard();

  ce.Enable(

    clipboard && (

      clipboard.IsClipboardFormatAvailable(CF_METAFILEPICT) ||

      clipboard.IsClipboardFormatAvailable(CF_DIB) ||

      clipboard.IsClipboardFormatAvailable(CF_BITMAP)

    )

  );

  clipboard.CloseClipboard();


See Also

TClipboard::GetClipboardData


TClipboard::OpenClipboard

See Also	TClipboard

Syntax

bool OpenClipboard(HWND Wnd);

Description

Opens the Clipboard and associates it with the window specified in Wnd. Other applications cannot change the clipboard data until the clipboard is closed. Returns true if successful; otherwise, returns false.


See Also

TClipboard::CloseClipboard


TClipboard::operator bool

TClipboard

Syntax

operator bool() const;

Description

Checks handle. Should use IsOk instead.


TClipboard::QueryCreate

See Also	TClipboard

Syntax

bool QueryCreate(const char far* protocol = DefaultProtocol, OLEOPT_RENDER renderopt = olerender_draw, OLECLIPFORMAT format = 0);

Description

QueryCreate determines if the object on the Clipboard supports the specified protocol and rendering options. DefaultProtocol points to a string specifying the name of the protocol the client application needs to use. renderopt specifies the client application's display and printing preference for the Clipboard object. renderopt is set to olerender_draw, which tells the client library to obtain and manage the data presentation. format specifies the Clipboard format the client application requests. The macros _OLE_H or _INC_OLE must be defined before this function can be used.


See Also

TClipboard::QueryLink


TClipboard::QueryLink

See Also	TClipboard

Syntax

bool QueryLink(const char far* protocol = DefaultProtocol, OLEOPT_RENDER renderopt = olerender_draw, OLECLIPFORMAT format = 0);

Description

QueryLink determines if a client application can use the Clipboard data to produce a linked object that uses the specified protocol and rendering options. See TClipboard::QueryCreate for a description of the parameters. The macros _OLE_H or _INC_OLE must be defined before this function can be used.


See Also

TClipboard::QueryCreate


TClipboard::RegisterClipboardFormat

See Also	TClipboard

Syntax

uint RegisterClipboardFormat(const char far* formatName) const;

Description

Registers a new Clipboard format. formatName points to a character string that identifies the new format. If the format can be registered, the return value indicates the registered format. If the format can't be registered, the return value is 0. Once the format is registered, it can be used as a valid format in which to render the data.


See Also

TClipboard::CountClipboardFormats

TClipboard::GetClipboardFormatName


TClipboard::SetClipboardData

See Also	TClipboard

Syntax

HANDLE SetClipboardData(uint format, HANDLE handle);

Description

Sets a handle to the block of data at the location indicated by handle. format specifies the format of the data block. The clipboard must have been opened before the data handle is set. format can be any one of the valid clipboard formats (for example, CF_BITMAP or CF_DIB).  See GetClipboardData for a list of these formats. handle is a handle to the memory location where the data data is stored. If successful, the return value is a handle to the data; if an error occurs, the return value is 0. Before the window is updated with the clipboard data, the clipboard must be closed.


See Also

TClipboard::GetClipboardData


TClipboard::SetClipboardViewer

See Also	TClipboard

Syntax

HWND SetClipboardViewer(HWND Wnd) const;

Description

Adds the window specified by Wnd to the chain of windows that WM_DRAWCLIPBOARD notifies whenever the contents of the Clipboard change.


See Also

TClipboard::GetClipboardViewer


TClipboard::IsOpen

TClipboard

Syntax

bool IsOpen;

Description

Returns true if the Clipboard is open.


TClipboard::TheClipboard

TClipboard

Syntax

static TClipboard TheClipboard;

Description

Holds the current clipboard.


TClipboard Protected Constructor

TClipboard

Syntax

TClipboard();

Description

Constructs a TClipboard object.


TClipboardViewer Class

OWL Hierarchy	Inheritance

Header File

clipview.h

Description

TClipboardViewer is a mix-in class that registers a TClipboardViewer as a Clipboard viewer when the user interface element is created, and removes itself from the Clipboard-viewer chain when it is destroyed.

Protected Data Member

HWND HWndNext;

Protected Constructors

TClipboardViewer();

TClipboardViewer(HWND hWnd, TModule* module = 0);

Protected Member Functions

TEventStatus DoChangeCBChain(HWND hWndRemoved, HWND hWndNext);

TEventStatus DoDestroy();

TEventStatus DoDrawClipboard();

void EvChangeCBChain(HWND hWndRemoved, HWND hWndNext);

void EvDestroy();

void EvDrawClipboard();

void SetupWindow();

Response Table Entries

EV_ macros and member functions


TClipboardViewer Protected Constructors

TClipboardViewer

Form 1

TClipboardViewer();

Form 2

TClipboardViewer(HWND hWnd, TModule* module = 0);

Description

Form 1: Constructs a TClipboardViewer object.

Description

Form 2: Constructs a TClipboardViewer object with a handle (hWnd) to the windows that will receive notification when the Clipboard's contents are changed.


TClipboardViewer::DoChangeCBChain

TClipboardViewer

Form 1

TEventStatus DoChangeCBChain(HWND hWndRemoved, HWND hWndNext);

Description

Tests to see if the Clipboard has changed and, if so, DoChangeCBChain forwards this message.


TClipboardViewer::DoDestroy

TClipboardViewer

Form 2

TEventStatus DoDestroy();

Description

Removes the window from the Clipboard-viewer chain.


TClipboardViewer::DoDrawClipboard

TClipboardViewer

Syntax

TEventStatus DoDrawClipboard();

Description

Handles EvDrawClipboard messages.


TClipboardViewer::EvChangeCBChain

TClipboardViewer

Syntax

void EvChangeCBChain(HWND hWndRemoved, HWND hWndNext);

Description

Responds to a WM_CHANGECBCHAIN message. hWndRemoved is a handle to the window that's being removed. hWndNext is the window following the removed window.


TClipboardViewer::EvDestroy

TClipboardViewer

Syntax

void EvDestroy();

Description

Responds to a WM_DESTROY message when a window is removed from the Clipboard-viewer chain.


TClipboardViewer::EvDrawClipboard

TClipboardViewer

Syntax

void EvDrawClipboard();

Description

Responds to a WM_DRAWCLIPBOARD message sent to the window in the Clipboard-viewer chain when the contents of the Clipboard change.


TClipboardViewer::SetupWindow

See Also	TClipboardViewer

Syntax

void SetupWindow();

Description

Adds a window to the Clipboard-viewer chain.


See Also

TWindow::SetupWindow


TClipboardViewer::HWndNext

TClipboardViewer

Syntax

HWND HWndNext;

Description

Specifies the next window in the Clipboard-viewer chain.


TClipboardViewer::Response Table Entries

TClipboardViewer

Response table entry	Member function

EV_WM_CHANGECBCHAIN	EvChangeCbChain

EV_WM_DESTROY	EvDestroy

EV_WM_DRAWCLIPBOARD	EvDrawClipBoard


TColor Class

OWL Hierarchy

Header File

color.h

Description

TColor is a support class used in conjunction with the classes TPalette, TPaletteEntry, TRgbQuad, and TRgbTriple to simplify all color operations. TColor has ten static data members representing the standard RGB COLORREF values, from Black to White. Constructors are provided to create TColor objects from COLORREF and RGB values, palette indexes, palette entries, and RGBQUAD and RGBTRIPLE values.

See the entries for NBits and NColors for a description of TColor-related functions.

Public Data Members

static const TColor Black;

static const TColor Gray;

static const TColor LtBlue;

static const TColor LtCyan;

static const TColor LtGray;

static const TColor LtGreen;

static const TColor LtMagenta;

static const TColor LtRed;

static const TColor LtYellow;

static const TColor White;

Public Constructors

TColor();

TColor(COLORREF value);

TColor(long value);

TColor(int r int g int b);

TColor(int r int g int b int f);

TColor(int index);

TColor(const PALETTEENTRY far& pe);

TColor(const RGBQUAD far& q);

TColor(const RGBTRIPLE far& t);

Public Member Functions

uint8 Blue() const;

uint8 Flags() const;

static TColor GetSysColor(int uiElement);

uint8 Green() const;

bool operator ==(const TColor& clrVal)const;

operator COLORREF() const;

int Index() const;

TColor PalIndex() const;

TColor PalRelative() const;

uint8 Red() const;

TColor Rgb() const;

static bool SetSysColors(unsigned nelems, const int indices[], const TColor colors[]);

Protected Data Member

COLORREF Value;


TColor::Black

TColor

Syntax

static const TColor Black;

Description

The static TColor object with fixed Value set by RGB(0, 0, 0).


TColor::Gray

TColor

Syntax

static const TColor Gray;

Description

Contains the static TColor object with fixed Value set by RGB(128, 128, 128).


TColor::LtBlue

TColor

Syntax

static const TColor LtBlue;

Description

Contains the static TColor object with the fixed Value set by RGB(0, 0, 255).


TColor::LtCyan

TColor

Syntax

static const TColor LtCyan;

Description

Contains the static TColor object with the fixed Value set by RGB(0, 255, 255).


TColor::LtGray

TColor

Syntax

static const TColor LtGray;

Description

Contains the static TColor object with the fixed Value set by RGB(192, 192, 192).


TColor::LtGreen

TColor

Syntax

static const TColor LtGreen;

Description

Contains the static TColor object with the fixed Value set by RGB(0, 255, 0).


TColor::LtMagenta

TColor

Syntax

static const TColor LtMagenta;

Description

Contains the static TColor object with the fixed Value set by RGB(255, 0, 255).


TColor::LtRed

TColor

Syntax

static const TColor LtRed;

Description

Contains the static TColor object with the fixed Value set by RGB(255, 0, 0).


TColor::LtYellow

TColor

Syntax

static const TColor LtYellow;

Description

Contains the static TColor object with the fixed Value set by RGB(255, 255, 0).


TColor::White

TColor

Syntax

static const TColor White;

Description

Contains the static TColor object with the fixed Value set by RGB(255, 255, 255).


TColor Public Constructors

See Also	TColor

Form 1

TColor();

Form 2

TColor(COLORREF value);

Form 3

TColor(long value);

Form 4

TColor(int r, int g, int b);

Form 5

TColor(int r, int g, int b, int f);

Form 6

TColor(int index);

Form 7

TColor(const PALETTEENTRY far& pe);

Form 8

TColor(const RGBQUAD far& q);

Form 9

TColor(const RGBTRIPLE far& t);

Description

Form 1: The default constructor sets Value to 0.

Form 2: Creates a TColor object with Value set to the given value.

Form 3: TColor(long value) : Value((COLORREF)value) {} Creates a TColor object with Value set to (COLORREF)value.

Form 4: Creates a TColor object with Value set to RGB(r,g,b).

Form 5: Creates a TColor object with Value set to RGB(r,g,b) with the flag byte formed from f.

Form 6: Creates a TColor object with Value set to PALETTEINDEX(index).

Form 7: Creates a TColor object with Value set to:

RGB(pe.peRed, pe.peGreen, pe.peBlue)

Form 8: Creates a TColor object with Value set to:

RGB(q.rgbRed, q.rgbGreen, q.rgbBlue)

Form 9: Creates a TColor object with Value set to:

RGB(t.rgbtRed, t.rgbtGreen, t.rgbtBlue)


See Also

COLORREF typedef

PALETTEENTRY struct

RGBQUAD struct

RGBTRIPLE struct

TColor::Value


TColor::Blue

See Also	TColor

Syntax

uint8 Blue() const;

Description

Returns the blue component of this color's Value.


See Also

TColor::Red

TColor::Green

COLORREF typedef


TColor::Flags

See Also	TColor

Syntax

uint8 Flags() const;

Description

Returns the peFlags value of this object's Value.


See Also

TPaletteEntry


TColor::GetSysColor

TColor

Syntax

static TColor GetSysColor(int uiElement);

Description

(Presentation Manager only) Returns the color of the given uiElement.


TColor::Green

See Also	TColor

Syntax

uint8 Green() const;

Description

Returns the green component of this color's Value.


See Also

TColor::Red

TColor::Blue

COLORREF typedef


TColor::operator ==

See Also	TColor

Syntax

bool operator ==(const TColor& clrVal);

Description

Returns true if this color's Value equals clrValue; otherwise returns false.


See Also

TColor::Value


TColor::operator COLORREF()

See Also	TColor

Syntax

operator COLORREF() const;

Description

Type-conversion operator that returns Value.


See Also

TColor::Value


TColor::Index

See Also	TColor

Syntax

int Index() const;

Description

Returns the index value corresponding to this color's Value by masking out the two upper bytes. Used when color is a palette index value.


See Also

TColor::Value

COLORREF typedef


TColor::PalIndex

See Also	TColor

Syntax

TColor PalIndex() const;

Description

Returns the palette index corresponding to this color's Value. The returned color has the high-order byte set to 1.


See Also

TColor::Value

TColor::Index

COLORREF typedef


TColor::PalRelative

See Also	TColor

Syntax

TColor PalRelative() const;

Description

Returns the palette-relative RGB corresponding to this color's Value. The returned color has the high-order byte set to 2.


See Also

TColor::Value

TColor::Rgb

COLORREF typedef


TColor::Red

See Also	TColor

Syntax

uint8 Red() const;

Description

Returns the red component of this color's Value.


See Also

TColor::Blue

TColor::Green


TColor::Rgb

See Also	TColor

Syntax

TColor Rgb() const;

Description

Returns the explicit RGB color corresponding to this color's Value by masking out the high-order byte.


See Also

TColor::Value

COLORREF typedef


TColor::SetSysColors

TColor

Syntax

static bool SetSysColors(unsigned nelems, const int uiElementIndices[], const TColor colors[]);

Description

(Presentation Manager only) Sets groups of UI element colors. nelems  indicates the number of element colors to change (and the size of the array parameters, uiElementIndices  indicates which elements to change, and colors  indicates what color to change the corresponding element to. Returns true if successful.


TColor::Value

See Also	TColor

Syntax

COLORREF Value;

Description

The color value of this TColor object. Value can have three different forms, depending on the application:

Explicit values for RGB (red, green, blue)

An index into a logical color palette

A palette-relative RGB value.


See Also

COLORREF typedef


TComboBox Class

OWL Hierarchy	Inheritance

Header File

combobox.h

Description

You can use TComboBox to create a combo box or a combo box control in a parent TWindow, or to facilitate communication between your application and the combo box controls of TDialog. TComboBox objects inherit most of their behavior from TListBox. This class is streamable.

There are three types of combo boxes: simple, drop down, and drop down list. These types are governed by the style constants CBS_SIMPLE, CBS_DROPDOWN, and CBS_DROPDOWNLIST. These constants, supplied to the constructor of a TComboBox, indicate the type of combo box element to create.

Public Data Member

uint TextLen;

Public Constructors

TComboBox(TWindow* parent, int id, int x, int y, int w, int h, uint32 style, uint textLen, TModule* module = 0);

TComboBox(TWindow* parent, int ResourceId, uint textLen = 0, TModule* module = 0);

Public Member Functions

virtual int AddString(const char far* string);

void Clear();

virtual void ClearList();

virtual int DeleteString(int index);

virtual int DirectoryList(uint attrs, const char far* fileSpec);

virtual int FindString(const char far* find, int indexStart) const;

virtual int GetCount() const;

void GetDroppedControlRect(TRect& Rect) const;

bool GetDroppedState() const;

int GetEditSel(int& startPos, int& endPos);

bool GetExtendedUI() const;

virtual uint32 GetItemData(int index) const;

int GetItemHeight(int index) const;

virtual int GetSelIndex() const;

virtual int GetString(char far* str, int index) const;

virtual int GetStringLen(int index) const;

int GetText(char far* str, int maxChars) const;

int GetTextLen() const;

void HideList();

virtual int InsertString(const char far* str, int index);

int SetEditSel(int startPos, int endPos);

int SetExtendedUI(bool extended);

virtual int SetItemData(int index, uint32 data);

int SetItemHeight(int index, int height);

virtual int SetSelIndex(int index);

virtual int SetSelString(const char far* findStr, int indexStart);

void SetText(const char far* string);

void ShowList();

void ShowList(bool show);

uint Transfer(void* buffer, TTransferDirection direction);

Protected Member Functions

virtual char far* GetClassName();

void SetupWindow();


TComboBox::TextLen

TComboBox

Syntax

uint TextLen;

Description

Contains the length of the text in the combo box's associated edit control.


TComboBox Public Constructors

See Also	TComboBox

Form 1

TComboBox(TWindow* parent, int id, int x, int y, int w, int h, uint32 style, uint textLen, TModule* module = 0);

Form 2

TComboBox(TWindow* parent, int ResourceId, uint textLen = 0, TModule* module = 0);

Description

Form 1: Constructs a combo box object with the specified parent window (parent), control ID (Id), position (x, y) relative to the origin of the parent window's client area, width (w), height (h), style (style), and text length (textLen).

Invokes the TListBox constructor with similar parameters. Then sets Attr.Style as follows:

Attr.Style = WS_CHILD | WS_VISIBLE | WS_GROUP | WS_TABSTOP | CBS_SORT | CBS_AUTOHSCROLL | WS_VSCROLL | style;

One of the following combo box style constants must be among the styles set in style: CBS_SIMPLE, CBS_DROPDOWN, CBS_DROPDOWNLIST, CBS_OWNERDRAWFIXED, or CBS_OWNERDRAWVARIABLE.

Form 2: Constructs a default combo box with the given parent window control ID text length.


See Also

TComboBox::GetTextLen

TListBox::TListBox


TComboBox::AddString

TComboBox

Syntax

virtual int AddString(const char far* string);

Description

Adds a string to an associated list part of a combo box. Returns the index of the string in the list. The first entry is at index zero. Returns a negative value if an error occurs.


TComboBox::Clear

TComboBox

Syntax

void Clear();

Description

Clears the text of the associated edit control.


TComboBox::ClearList

TComboBox

Syntax

virtual void ClearList();

Description

Clears out all associated entries in the associated list.


TComboBox::DeleteString

TComboBox

Syntax

virtual int DeleteString(int index);

Description

Deletes the string at the passed index in the associated list part of a combo box. Returns a count of the entries remaining in the list or a negative value if an error occurs.


TComboBox::DirectoryList

TComboBox

Syntax

virtual int DirectoryList(uint attrs, const char far* fileSpec);

Description

Fills the combo box with file names from a specified directory.


TComboBox::FindString

TComboBox

Syntax

virtual int FindString(const char far* find, int indexStart) const;

Description

Searches for a match beginning at the passed Index. If a match is not found after the last string has been compared, the search continues from the beginning of the list until a match is found or until the list has been completely traversed. Returns the index of the first string in the associated list part of a combo box or a negative value if an error occurs.


TComboBox::GetCount

TComboBox

Syntax

virtual int GetCount() const;

Description

Returns the number of entries in the associated list part of the combo box or a negative value if an error occurs.


TComboBox::GetDroppedControlRect

TComboBox

Syntax

void GetDroppedControlRect(TRect& Rect) const;

Description

For combo boxes, gets the screen coordinates of the dropped down list box.


TComboBox::GetDroppedState

TComboBox

Syntax

bool GetDroppedState() const;

Description

For drop down combo boxes, determines if a list box is visible.


TComboBox::GetEditSel

TComboBox

Syntax

int GetEditSel(int &startPos, int &endPos);

Description

Returns the starting and ending positions of the text selected in the associated edit control. Returns CB_ERR if the combo box has no edit control.


TComboBox::GetExtendedUI

See Also	TComboBox

Syntax

bool GetExtendedUI() const;

Description

Determines if the combo box has the extended user interface, which differs from the default user interface in the following ways:

Displays the list box if the user clicks the static text field.

Displays the list box if the user presses the Down key.

Disables scrolling in the static text field if the item list is not visible.

Returns true if the combo box has the extended user interface;  otherwise returns false.


See Also

TComboBox::SetExtendedUI


TComboBox::GetItemData

See Also	TComboBox

Syntax

virtual uint32 GetItemData(int index) const;

Description

Returns the 32-bit value associated with the combo box's item.


See Also

TListBox::GetItemData


TComboBox::GetItemHeight

See Also	TComboBox

Syntax

int GetItemHeight(int index) const;

Description

Returns the height in pixels of the Combo box's list items. If an error occurs, returns a negative value.


See Also

TComboBox::GetItemData

TListBox::GetItemData


TComboBox::GetSelIndex

TComboBox

Syntax

virtual int GetSelIndex() const;

Description

Returns the index of the list selection or a negative value if none exists.


TComboBox::GetString

See Also	TComboBox

Syntax

virtual int GetString(char far* str, int index) const;

Description

Retrieves the contents of the string at the position supplied in index and returns it in string. GetString returns the string length or a negative value if an error occurs. The buffer must be large enough for the string and the terminating zero.


See Also

TListBox::GetString


TComboBox::GetStringLen

See Also	TComboBox

Syntax

virtual int GetStringLen(int index) const;

Description

Returns the string length (excluding the terminating zero) of the item at the position index supplied in index. Returns a negative value if an error occurs.


See Also

TListBox::GetStringLen


TComboBox::GetText

TComboBox

Syntax

int GetText(char far* str, int maxChars) const;

Description

Retrieves the number of characters in the edit or static portion of the combo box.


TComboBox::GetTextLen

TComboBox

Syntax

int GetTextLen() const;

Description

Returns the text length (excluding the terminating zero) of the edit control or static portion of the combo box.


TComboBox::HideList

TComboBox

Syntax

void HideList();

Description

Hides the drop down list of a drop down or drop down list combo box.


TComboBox::InsertString

See Also	TComboBox

Syntax

virtual int InsertString(const char far* str, int index);

Description

Inserts a string in the associated list part of a combo box at the position supplied in Index. Returns the index of the string in the list or a negative value if an error occurs.


See Also

TListBox::InsertString


TComboBox::SetEditSel

TComboBox

Syntax

int SetEditSel(int startPos, int endPos);

Description

Selects characters that are between startPos and endPos in the edit control of the combo box. Returns CB_ERR if the combo box does not have an edit control.


TComboBox::SetExtendedUI

See Also	TComboBox

Syntax

int SetExtendedUI(bool extended);

Description

If the combo box has the extended user interface, sets the extended user interface.


See Also

TComboBox::GetExtendedUI


TComboBox::SetItemData

TComboBox

Syntax

virtual int SetItemData(int index, uint32 data);

Description

Sets the 32-bit value associated with the TComboBox's item. If an error occurs, returns a negative value.


TComboBox::SetItemHeight

See Also	TComboBox

Syntax

int SetItemHeight(int index, int height);

Description

Sets the height of the list items or the edit control portion in a combo box. If the index or height is invalid, returns a negative value.


See Also

TComboBox::GetItemHeight


TComboBox::SetSelIndex

See Also	TComboBox

Syntax

virtual int SetSelIndex(int index);

Description

Selects a string of characters in a combo box. index specifies the index of the string of characters in the list box to select. If the index is 0, the first line in the list box is selected. If the index is -1, the current selection is removed. If an error occurs, a negative value is returned.


See Also

TComboBox::GetSelIndex


TComboBox::SetSelString

TComboBox

Syntax

virtual int SetSelString(const char far* findStr, int indexStart);

Description

Selects a string of characters in the associated list box and sets the contents of the associated edit control to the supplied string.


TComboBox::SetText

TComboBox

Syntax

void SetText(const char far* string);

Description

Selects the first string in the associated list box that begins with the supplied string. If there is no match, SetText sets the contents of the associated edit control to the supplied string and selects it.


TComboBox::ShowList

See Also	TComboBox

Form 1

void ShowList();

Form 2

void ShowList(bool show);

Description

Form 1: Shows the list of a drop down or drop down list combo box.

Form 2: Shows or hides the drop down or drop down list combo box depending on the value of show. If show is true, shows the list; if show is false, hides the list.


See Also

TComboBox::HideList


TComboBox::Transfer

See Also	TComboBox

Synta

x

uint Transfer(void* buffer, TTransferDirection direction);

Description

Transfers the items and selection of the combo box to or from a transfer buffer if tdSetData or tdGetData, respectively, is passed as the direction. buffer is expected to point to a TComboBoxData structure.

Transfer returns the size of a pointer to a TComboBoxData. To retrieve the size without transferring data, your application must pass tdSizeData as the direction.

You must use a pointer in your transfer buffer to these structures. You cannot embed copies of the structures in your transfer buffer, and you cannot use these structures as transfer buffers.


See Also

TComboBoxData

TWindow::Transfer


See Also

TWindow::SetupWindow


TComboBox::GetClassName

TComboBox

Syntax

virtual char far* GetClassName();

Description

Returns the name of TComboBox's registration class, "ComboBox."


TComboBox::SetupWindow

See Also	TComboBox

Syntax

void SetupWindow();

Description

Sets up the window and limits the amount of text the user can enter in the combo box's edit control to the value of TextLen minus 1.


TComboBoxData Class

OWL Hierarchy	Inheritance

Header File

combobox.h

Description

An interface object that represents a transfer buffer for a TComboBox.

Public Constructor and Destructor

TComboBoxData();

~TComboBoxData();

Public Member Functions

void AddString(const char *str, bool isSelected = false);

void AddStringItem(const char* str, uint32 itemData, bool isSelected = false);

void Clear();

TDwordArray& GetItemDatas();

int GetSelCount() const;

string& GetSelection();

int GetSelIndex();

void GetSelString(char far* buffer, int bufferSize) const;

int GetSelStringLength() const;

TStringArray& GetStrings();

void ResetSelections();

void Select(int index);

void SelectString(const char far* str);

Protected Data Members

TDwordArray ItemDatas;

string Selection;

int SelIndex;

TStringArray Strings;


TComboBoxData::ItemDatas

TComboBoxData

Syntax

TDwordArray ItemDatas;

Description

Array of DWORDs to transfer to or from a combo box's associated list box.


TComboBoxData::Selection

TComboBoxData

Syntax

string Selection;

Description

The currently selected string to transfer to or from a combo box.


TComboBoxData::SelIndex

TComboBoxData

Syntax

int SelIndex;

Description

Index of the selected item in the strings array.


TComboBoxData::Strings

TComboBoxData

Syntax

TStringArray Strings;

Description

Array of class string to transfer to or from a combo box's associated list box.


TComboBoxData Public Constructor and Destructor

TComboBoxData

Constructor

TComboBoxData();

Destructor

~TComboBoxData();

Description

Constructs a TComboBoxData object, initializes Strings and ItemDatas to empty arrays, and initializes Selection and SelIndex to 0.

Destructor

Deletes Strings, ItemDatas, and Selection.


TComboBoxData::AddString

TComboBoxData

Syntax

void AddString(const char *str, bool isSelected = false);

Description

Adds the specified string to the array of Strings. If IsSelected is true, AddString deletes Selection and copies string into Selection.


TComboBoxData::AddStringItem

TComboBoxData

Syntax

void AddStringItem(const char* str, uint32 itemData, bool isSelected = false);

Description

Calls AddItemData to add the item data to the ItemDatas array, and calls AddString to add a string to the array of Strings.


TComboBoxData::GetStrings

TComboBoxData

Syntax

TStringArray& GetStrings();

Description

Returns the array of strings (the Strings data member) to transfer to or from a combo box's associated list box.


TComboBoxData::GetItemDatas

TComboBoxData

Syntax

TDwordArray& GetItemDatas();

Description

Returns the array of DWORDs to transfer to or from a combo box's associated list box.


TComboBoxData::GetSelIndex

TComboBoxData

Syntax

int GetSelIndex();

Description

Returns the index (the SelIndex data member) of the selected item in the strings array.


TComboBoxData::GetSelection

TComboBoxData

Syntax

string& GetSelection();

Description

Returns the currently selected string (the Selection data member) to transfer to or from a combo box.


TComboBoxData::Clear

TComboBoxData

Syntax

void Clear();

Description

Flushes the Strings and ItemDatas members. Resets the index and selected string values.


TComboBoxData::Select

TComboBoxData

Syntax

void Select(int index);

Description

Selects the item at the given index.


TComboBoxData::SelectString

TComboBoxData

Syntax

void SelectString(const char far* str);

Description

Selects the selection string (str) and makes the matching String entry (if one exists) as selected.


TComboBoxData::GetSelCount

TComboBoxData

Syntax

int GetSelCount() const;

Description

Returns the number of items selected, either 0 or 1.


TComboBoxData::ResetSelections

TComboBoxData

Syntax

void ResetSelections();

Description

Resets the index of the selected item and the currently selected string.


TComboBoxData::GetSelStringLength

TComboBoxData

Syntax

int GetSelStringLength() const;

Description

Returns length of the currently selected string excluding the terminating 0.


TComboBoxData::GetSelString

TComboBoxData

Syntax

void GetSelString(char far* buffer, int bufferSize) const;

Description

Copies the selected string into a buffer of the specified size. bufferSize includes the terminating 0.


TCommandEnabler Class

See Also	OWL Hierarchy	Inheritance

Header file

window.h

Description

An abstract base class used for automatic enabling and disabling of commands, TCommandEnabler is a class from which you can derive other classes, each one having its own command enabler. For example, TButtonGadgetEnabler is a derived class that's a command enabler for button gadgets, and TMenuItemEnabler is a derived class that's a command enabler for menu items. Although your derived classes are likely to use only the functions Enable, SetCheck, and GetHandled, all of TCommandEnabler's functions are described so that you can better understand how ObjectWindows uses command processing. The following paragraphs explain the dynamics of command processing .

Handling command messages

Commands are messages of the windows WM_COMMAND type that have associated command identifiers (for example, CM_FILEMENU). When the user selects an item from a menu or a toolbar, when a control sends a notification message to its parent window, or when an accelerator keystroke is translated, a WM_COMMAND message is sent to a window.

Responding to command messages

A command is handled differently depending on which type of command a window receives. Menu items and accelerator commands are handled by adding a command entry to a message response table using the EV_COMMAND macro. The entry requires two arguments:

A command identifier (for example, CM_LISTUNDO)

A member function (for example, CMEditUndo)

Child ID notifications, messages that a child window sends to its parent window, are handling by using one of the notification macros defined in the header file windowev.h.

It is also possible to handle a child ID notification at the child window by adding an entry to the child's message response table using the EV_NOTIFY_AT_CHILD macro. This entry requires the following arguments:

A notification message (for example, LBN_DBLCLK)

A member function (for example, CmEditItem)

TWindow command processing

One of the classes designed to handle command processing, TWindow performs basic command processing according to these steps;

1.	The member function WindowProc calls the virtual member function EvCommand.

2.	EvCommand checks to see if the window has requested handling the command by looking up the command in the message response table.

3.	If the window has requested handling the command identifier by using the EV_COMMAND macro, the command is dispatched.

TWindow also handles Child ID notifications at the child window level.

TFrameWindow command processing

TFrameWindow provides specialized command processing by overriding its member function EvCommand and sending the command down the command chain (that is, the chain of windows from the focus window back up to the frame itself, the original receiver of the command message).

If no window in the command chain handles the command, TFrameWindow delegates the command to the application object. Although this last step is theoretically performed by the frame window, it is actually done by TWindow's member function, DefaultProcessing.

Invoking EvCommand

When TFrameWindow sends a command down the command chain, it does not directly dispatch the command; instead, it invokes the window's EvCommand member function. This procedure gives the windows in the command chain the flexibility to handle a command by overriding the member function EvCommand instead of being limited to handling only the commands requested by the EV_COMMAND macro.

Handling command enable messages

Most applications expend considerable energy updating menu items and tool bar buttons to provide the necessary feedback indicating that a command has been enabled. In order to simplify this procedure, ObjectWindows lets the event handler that is going to handle the command make the decision about whether or not to enable or disable a command.

Although the WM_COMMAND_ENABLE message is sent down the same command chain as the WM_COMMAND event; exactly when the WM_COMMAND_ENABLE message is sent depends on the type of command enabling that needs to be processed.

Command enabling for menu items

TFrameWindow performs this type of command enabling when it receives a WM_INITMENUPOPUP message. It sends this message before a menu list appears. ObjectWindows then identifies the menu commands using the command IDs and sends requests for the commands to be enabled.

Note that because Object Windows actively maintains toolbars and menu items, any changes made to the variables involved in the command enabling functions are implemented dynamically and not just when a window is activated.

Command enabling for toolbar buttons

This type of command enabling is performed during idle processing (in the IdleAction function). The Default Message-Processing Flowchart that accompanies TWindow::DefaultProcessingis a graphical illustration of this process.

Creating specialized command enablers

Associated with the WM_COMMAND_ENABLE message is an object of the TCommandEnabler type. This family of command enablers includes specialized command enablers for menu items and toolbar buttons.

 As you can see from TCommandEnabler's class declaration, you can do considerably more than simply enable or disable a command using the command enabler. For example, you have the ability to change the text associated with the command as well as the state of the command.

Using the EV_COMMAND_ENABLE macro

You can use the EV_COMMAND_ENABLE macro to handle WM_COMMAND_ENABLE  messages. Just as you do with the EV_COMMAND macro, you specify the command identifier that you want to handle and the member function you want to invoke to handle the message.

Automatically enabling and disabling commands

ObjectWindows simplifies enabling and disabling of commands by automatically disabling commands for which there are no associated handlers. TFrameWindow's member function EvCommandEnable performs this operation, which involves completing a two-pass algorithm.

1.	The first pass sends a WM_COMMAND_ENABLE message down the command chain giving each window an explicit opportunity to do the command enabling.

2.	If no window handles the command enabling request, then ObjectWindows checks to see whether any windows in the command chain are going to handle the command through any associated EV_COMMAND entries in their response tables. If there is a command handler in one of the response tables, then the command is enabled; otherwise it is disabled.

Because of this implicit command enabling or disabling, you do not need to (and actually should not) do explicit command enabling unless you want to change the command text, change the command state, or conditionally enable or disable the command.

If you handle commands indirectly by overriding the member function EvCommand instead of using the  EV_COMMAND macro to add a response table entry, then ObjectWindows will not be aware that you are handling the command. Consequently, the command may be automatically disabled. Should this occur, the appropriate action to take is to also override the member function EvCommandEnable and explicitly enable the command.

Type Definitions

enum CheckState {Unchecked, Checked, Indeterminate};

Public Data Members

const uint Id;

Public Constructor

TCommandEnabler(uint id, HWND hWndReceiver = 0);

Public Member Functions

virtual void Enable(bool enable = true);

bool GetHandled();

bool IsReceiver(HWND hReceiver);

virtual void SetCheck(int check) = 0;

virtual void SetText(const char far* text) = 0;

Protected data members

bool Handled;

const HWND HWndReceiver;


See Also

Command Enabling Overview


TCommandEnabler::Id

TCommandEnabler

Syntax

const uint Id;

Description

Command ID for the enabled command.


TCommandEnabler::CheckState enum

TCommandEnabler

Syntax

enum CheckState{Unchecked, Checked, Indeterminate};

Description

Enumerates the values for the check state of the command sender. This state applies to buttons, such as those used for tool bars or to control bar gadgets.


TCommandEnabler Public Constructor

TCommandEnabler

Syntax

TCommandEnabler(uint id, HWND hWndReceiver = 0);

Description

Constructs the TCommandEnabler object with the specified command ID. Sets the message responder (hWndReceiver) to zero.


TCommandEnabler::Enable

TCommandEnabler

Syntax

virtual void Enable(bool enable = true);

Description

Enables or disables the command sender. When Enable is called, it sets the Handled flag.


TCommandEnabler::GetHandled

TCommandEnabler

Syntax

bool GetHandled();

Description

Returns  Handled, a flag value that shows if this command enabler has been handled, in which case Handled is true.


TCommandEnabler::IsReceiver

TCommandEnabler

Syntax

bool IsReceiver(HWND hReceiver);

Description

Returns true if receiver is the same as the message responder originally set up in the constructor.


TCommandEnabler::SetCheck

TCommandEnabler

Syntax

virtual void SetCheck(int check) = 0;

Description

Changes the check state of the command sender to either unchecked, checked,  or indeterminate. This state applies to buttons, such as those used for tool bars or to control bar gadgets.


TCommandEnabler::SetText

TCommandEnabler

Syntax

virtual void SetText(const char far* text) = 0;

Description

Changes the text associated with a command sender; for example, text associated with a menu item or text on a button.


TCommandEnabler::HWndReceiver

TCommandEnabler

Syntax

const HWND HWndReceiver;

Description

The message responder (the window) that receives the command.


TCommandEnabler::Handled

TCommandEnabler

Syntax

bool Handled;

Description

Is true if the command enabler has been handled.


TCommonDialog Class

OWL Hierarchy	Inheritance

Header File

commdial.h

Description

Derived from TDialog, TCommonDialog is the abstract base class for TCommonDialog objects. It provides the basic functionality for creating dialog boxes using the common dialog DLL. The ObjectWindows classes that inherit this common dialog functionality include

TChooseColorDialog- a modal dialog box that lets a user select colors for an application.

TChooseFontDialog - a modal dialog box that lets a user select fonts for an application.

TReplaceDialog- a modeless dialog box that lets a user specify a text selection to replace.

TFindDialog- a modeless dialog box that lets a user specify a text selection to find.

TFileOpenDialog- a modal dialog box that lets a user specify a file to open.

TFileSaveDialog- a modal dialog box that lets a user specify a file to save.

TPrintDialog- a modal dialog box that lets a user specify printer options.

Each common dialog class uses a nested class, TData, that stores the attributes and user-specified data. For example, the TChooseColorDialog::TData class stores the color attributes the user selects in response to a prompt in a common dialog box. In fact, to create a common dialog box, you construct a TData object first, then fill in the data members of the TData object before you even construct the common dialog box object. Finally, you either execute a modal dialog box or create a modeless dialog box.

Public Constructor

TCommonDialog(TWindow* parent, const char far* title = 0, TModule* module = 0);

Public Member Functions

HWND DoCreate();

int DoExecute();

Protected Data Member

const char far* CDTitle;

Protected Member Functions

void CmHelp();

void CmOkCancel();

void EvClose();

void SetupWindow();

Response Table Entries

EV_ macros and member functions


 TCommonDialog Public Constructor

TCommonDialog

Syntax

TCommonDialog(TWindow* parent, const char far* title = 0, TModule* module = 0);

Description

Invokes a TWindow constructor, passing the parent window parent, and constructs a common dialog box that you can modify to suit your specifications. You can indicate the module ID (module) and window caption (title), which otherwise default to 0.


TCommonDialog::DoCreate

TCommonDialog

Syntax

HWND DoCreate();

Description

Called by Create, DoCreate creates a modeless dialog box. It returns 0 if unsuccessful.


TCommonDialog::DoExecute

TCommonDialog

Syntax

int DoExecute();

Description

Called by Execute, DoExecute executes a modal dialog box. If the dialog box execution is canceled or unsuccessful, DoExecute returns IDCANCEL.


TCommonDialog::CDTitle

See Also	TCommonDialog

Syntax

const char far* CDTitle;

Description

CDTitle stores the optional caption displayed in the common dialog box.


See Also

TDialog::SetCaption


TCommonDialog::CmHelp

TCommonDialog

Syntax

void CmHelp();

Description

Default handler for the pshHelp push button (the Help button in the dialog box).


TCommonDialog::CmOkCancel

See Also	TCommonDialog

Syntax

void CmOkCancel();

Description

Responds to a click on the dialog box's OK or Cancel button by calling DefaultProcessing to let the common dialog DLL process the command.


See Also

TDialog::CmCancel

TDialog::CmOk


TCommonDialog::EvClose

See Also	TCommonDialog

Syntax

void EvClose();

Description

Responds to a WM_CLOSE message by calling DefaultProcessing to let the common dialog DLL process the command.


See Also

TDialog::EvClose


TCommonDialog::SetupWindow

See Also	TCommonDialog

Syntax

void SetupWindow();

Description

Assigns the caption of the dialog box to CDTitle if CDTitle is nonzero.


See Also

TDialog::SetupWindow


TCommonDialog Response Table Entries

TCommonDialog

Response table entry	Member function

EV_COMMAND(IDCANCEL, CmOkCancel)	CmOkCancel

EV_COMMAND(IDOK, CmOkCancel)	CmOkCancel

EV_WM_CLOSE	EvClose

EV_WM_CTLCOLOR	EvCtlColor


TCondFunc typedef

SeeAlso	OWL Hierarchy

Header File

window.h

Syntax

typedef bool (*TCondFunc) (TWindow *win, void *param);

Description

Defines a member function type used by TWindow's function FirstThat.


See Also

TWindow::FirstThat


TCondMemFunc typedef

OWL Hierarchy	See Also

Header File

window.h

Syntax

typedef bool (TWindow_TCondMemFunc) (*win, void *param);

Description

Defines a member function type used by TWindow's function FirstThat.


See Also

TWindow::FirstThat


TControlBar Class

OWL Hierarchy	Inheritance

Header File

controlb.h

Description

Derived from TGadgetWindow, TControlBar implements a control bar that provides mnemonic access for its button gadgets. The sample MDIFILE.CPP ObjectWindows program on your distribution disk displays the following example of a control bar:

To construct, build, and insert a control bar into a frame window, you can first define the following response table:

DEFINE_RESPONSE_TABLE1(TMDIFileApp, TApplication)

EV_COMMAND(CM_FILENEW, CmFileNew),

EV_COMMAND(CM_FILEOPEN, CmFileOpen),

EV_COMMAND(CM_SAVESTATE, CmSaveState),

EV_COMMAND(CM_RESTORESTATE, CmRestoreState),

END_RESPONSE_TABLE;

Next, add statements that will construct a main window and load its menu, accelerator table, and icon. Then, to construct, build and insert a control bar into the frame window, insert these statements:

TControlBar* cb = new TControlBar(frame);

cb->Insert(*new TButtonGadget(CM_FILENEW, CM_FILENEW));

cb->Insert(*new TButtonGadget(CM_FILEOPEN, CM_FILEOPEN));

cb->Insert(*new TButtonGadget(CM_FILESAVE, CM_FILESAVE));

cb->Insert(*new TSeparatorGadget(6));

cb->Insert(*new TButtonGadget(CM_EDITCUT, CM_EDITCUT));

cb->Insert(*new TButtonGadget(CM_EDITCOPY, CM_EDITCOPY));

cb->Insert(*new TButtonGadget(CM_EDITPASTE, CM_EDITPASTE));

cb->Insert(*new TSeparatorGadget(6));

cb->Insert(*new TButtonGadget(CM_EDITUNDO, CM_EDITUNDO));

frame->Insert(*cb, TDecoratedFrame::Top);

Public Constructor

TControlBar(TWindow* parent = 0, TTileDirection direction = Horizontal, TFont* font = new TGadgetWindowFont, TModule* module = 0);

Public Member Function

bool PreProcessMsg(MSG& msg);

Protected Member Function

void PositionGadget(TGadget* previous, TGadget* next, TPoint& p);


TControlBar Public Constructor

TControlBar

Syntax

TControlBar(TWindow* parent = 0, TTileDirection direction = Horizontal, TFont* font = new TGadgetWindowFont, TModule* module = 0);

Description

Constructs a TControlBar interface object with the specified direction (either horizontal or vertical) and window font.


TControlBar::PreProcessMsg

TControlBar

Syntax

bool PreProcessMsg(MSG& msg);

Description

Preprocesses messages. Because PreProcessMsg does not translate any accelerator keys for TControlBar, it returns false.


TControlBar::PositionGadget

TControlBar

Syntax

void PositionGadget(TGadget* previous, TGadget* next, TPoint& p);

Description

Gets the border style, determines the direction of the gadget, and positions the button gadget on either a horizontal or vertical border if any overlapping is required.


TControlGadget Class

See Also	OWL Hierarchy	Inheritance

Header File

controlg.h

Description

TControlGadget serves as a surrogate for TControl so that you can place TControl objects such as edit controls, buttons, sliders, gauges, or third-party controls, into a gadget window. If necessary, TControlGadget sets a parent window and creates the control gadget. See TGadget for more information about gadget objects.

Public Constructor and Destructor

TControlGadget(TWindow& control, TBorderStyle = None);

~TControlGadget();

Protected Data Member

TWindow* Control;

Protected Member Functions

void GetDesiredSize(TSize& size);

void GetInnerRect(TRect&);

void Inserted();

void Invalidate(bool erase = true);

void InvalidateRect(const TRect&, bool erase = true);

void Removed();

void SetBounds(TRect& rect);

void Update();

Response Table Entries

TControlGadget Response Table Entries


See Also

TGadget


TControlGadget Public Constructor and Destructor

TControlGadget

Constructor

TControlGadget(TWindow& control, TBorderStyle = None);

Destructor

~TControlGadget();

Description

Creates a TControlGadget object associated with the specified TControl window.

Destructor

Destroys a TControlGadget object and removes it from the associated window.


TControlGadget::Control

TControlGadget

Syntax

TWindow* Control;

Description

Points to the control window that is managed by this TControlGadget.


TControlGadget::GetDesiredSize

See Also	TControlGadget

Syntax

void GetDesiredSize(TSize& size);

Description

Calls TGadget::GetDesiredSize and passes the size of the control gadget. Use GetDesiredSize to find the size the control gadget needs to be in order to accommodate the borders and margins as well as the highest and widest control gadget.


See Also

TGadget::GetDesiredSize


TControlGadget::GetInnerRect

TControlGadget

Syntax

void GetInnerRect(TRect&);

Description

Computes the area of the control gadget's rectangle excluding the borders and margins.


TControlGadget::Inserted

TControlGadget

Syntax

void Inserted();

Description

Called when the control gadget is inserted in the parent window. Displays the window in its current size and position.


TControlGadget::Invalidate

TControlGadget

Syntax

void Invalidate(bool erase = true);

Description

Used to invalidate the active (usually nonborder) portion of the control gadget, Invalidate calls InvalidateRect and passes the boundary width and height of the area to erase.


TControlGadget::InvalidateRect

TControlGadget

Syntax

void InvalidateRect(const TRect&, bool erase = true);

Description

Invalidates the control gadget rectangle in the parent window.


TControlGadget::Removed

TControlGadget

Syntax

void Removed();

Description

Called when the control gadget is removed from the parent window.


TControlGadget::SetBounds

See Also	TControlGadget

Syntax

void SetBounds(TRect& rect);

Description

Calls TGadget::SetBounds and passes the dimensions of the control gadget's rectangle. SetBounds informs the control gadget of a change in its bounding rectangle.


See Also

TGadget::SetBounds


TControlGadget::Update

TControlGadget

Syntax

void Update();

Description

Updates the client area of the specified window by immediately sending a WM_PAINT message.


TControlGadget::Response Table Entries
TControlGadget Response Table Entries

TControlGadget

The TControlGadget class has no response table entries.


TControl Class

OWL Hierarchy	Inheritance

Header File

control.h

Description

TControl unifies its derived control classes, such as TScrollBar, TControlGadget, and TButton. Control objects of derived classes are used to represent control interface elements. A control object must be used to create a control in a parent TWindow object or a derived window. A control object can be used to facilitate communication between your application and the controls of a TDialog object. TControl is a streamable class.

Public Constructors

TControl(TWindow* parent, int id, const char far* title, int x, int y, int w, int h, TModule* module = 0);

TControl(TWindow* parent, int resourceId, TModule* module = 0);

Protected Member Functions

virtual int CompareItem(COMPAREITEMSTRUCT far& compareInfo);

virtual void DeleteItem(DELETEITEMSTRUCT far& deleteInfo);

virtual void DrawItem(DRAWITEMSTRUCT far& drawInfo);

LRESULT EvCompareItem(uint ctrlId, COMPAREITEMSTRUCT far& comp);

virtual void EvDeleteItem(uint ctrlId, DELETEITEMSTRUCT far& deleteInfo);

void EvDrawItem(uint ctrlId, DRAWITEMSTRUCT far& draw);

void EvMeasureItem(uint ctrlId, MEASUREITEMSTRUCT far& meas);

void EvPaint();

virtual void MeasureItem(MEASUREITEMSTRUCT far& measureInfo);

virtual void ODADrawEntire(DRAWITEMSTRUCT far& drawInfo);

virtual void ODAFocus(DRAWITEMSTRUCT far& drawInfo);

virtual void ODASelect(DRAWITEMSTRUCT far& drawInfo);

Response Table Entries

EV_ macros and member functions


TControl Public Constructors

TControl

Syntax 1

TControl(TWindow* parent, int id, const char far* title, int x, int y, int w, int h, TModule* module = 0);

Description

Invokes TWindow's constructor, passing it parent (parent window), title (caption text), and module. Sets the control attributes using the supplied library ID (Id), position (x, y) relative to the origin of the parent window's client area, width (w), and height (h) parameters. It sets the control style to WS_CHILD | WS_VISIBLE | WS_GROUP | WS_TABSTOP.

Syntax 2

TControl(TWindow* parent, int resourceId, TModule* module = 0);

Description

Constructs an object to be associated with an interface control of a TDialog object. Invokes the  TWindow constructor, then enables the data transfer mechanism by calling TWindow::EnableTransfer.

The id parameter must correspond to a control interface resource that you define.


TControl::CompareItem

See Also	TControl

Syntax

virtual int CompareItem (COMPAREITEMSTRUCT far& compareInfo);

Description

Also used with owner-draw buttons and list boxes, CompareItem compares two items. The derived class supplies the compare logic.


See Also

COMPAREITEMSTRUCT struct


TControl::DeleteItem

See Also	TControl

Syntax

virtual void DeleteItem (DELETEITEMSTRUCT far& deleteInfo);

Description

Used with owner-draw buttons and list boxes. In such cases, the derived class supplies the delete logic.


See Also

DELETEITEMSTRUCT struct


TControl::DrawItem

See Also	TControl

Syntax

virtual void DrawItem(DRAWITEMSTRUCT far& drawInfo);

Description

Responds to a message forwarded by TWindow to a drawable control when the control needs to be drawn. DrawItem calls one of the following: ODADrawEntire if the entire control needs to be drawn, ODASelect if the selection state of the control has changed, or ODAFocus if the focus has been shifted to or from the control.


See Also

DRAWITEMSTRUCT struct


TControl::EvCompareItem

See Also	TControl

Syntax

LRESULT EvCompareItem(uint ctrlId, COMPAREITEMSTRUCT far& comp);

Description

Handles a WM_COMPAREITEM message for owner-draw controls.


See Also

COMPAREITEMSTRUCT struct


TControl::EvDeleteItem

See Also	TControl

Syntax

void EvDeleteItem(uint ctrlId, DELETEITEMSTRUCT far& del);

Description

Handles a WM_DELETEITEM message for owner-draw controls.


See Also

DELETEITEMSTRUCT struct


TControl::EvDrawItem

See Also	TControl

Syntax

void EvDrawItem(uint ctrlId, DRAWITEMSTRUCT far& draw);

Description

Handles a WM_DRAWITEM message.


See Also

DRAWITEMSTRUCT struct


TControl::EvMeasureItem

See Also	TControl

Syntax

void EvMeasureItem(uint ctrlId, MEASUREITEMSTRUCT far& meas);

Description

Handles a WM_MEASUREITEM message.


See Also

MEASUREITEMSTRUCT struct


TControl::EvPaint

See Also	TControl

Syntax

void EvPaint();

Description

If the control has a predefined class, EvPaint calls TWindow::DefaultProcessing for  painting. Otherwise, it calls TWindow::EvPaint.


See Also

TWindow::Paint


TControl::MeasureItem

See Also	TControl

Syntax

virtual void MeasureItem (MEASUREITEMSTRUCT far& measureInfo);

Description

Used by owner-drawn controls to set the dimensions of the specified item. For list boxes and control boxes, this function applies to specific items; for other owner-drawn controls, this function is used to set the total size of the control.


See Also

MEASUREITEMSTRUCT struct


TControl::ODADrawEntire

See Also	TControl

Syntax

virtual void ODADrawEntire(DRAWITEMSTRUCT far& drawInfo);

Description

Responds to a notification message sent to a drawable control when the control needs to be drawn. ODADrawEntire can be redefined by a drawable control to specify the manner in which it is to be drawn.


See Also

TControl::DrawItem

DRAWITEMSTRUCT struct


TControl::ODAFocus

See Also	TControl

Syntax

virtual void ODAFocus(DRAWITEMSTRUCT far& drawInfo);

Description

Responds to a notification sent to a drawable control when the focus has shifted to or from the control. ODAFocus can be redefined by a drawable control to specify the manner in which it is to be drawn when losing or gaining the focus.


See Also

TControl::DrawItem

DRAWITEMSTRUCT struct


TControl::ODASelect

See Also	TControl

Syntax

virtual void ODASelect(DRAWITEMSTRUCT far& drawInfo);

Description

Responds to a notification sent to a drawable control when the selection state of the control changes. ODASelect can be redefined by a drawable control to specify the manner in which it is drawn when its selection state changes.


See Also

TControl::DrawItem

DRAWITEMSTRUCT struct


TControl Response Table Entries

TControl

Response table entry	Member function

EV_WM_PAINT	EvPaint

EV_WM_COMPAREITEM	EvCompareItem

EV_WM_DELETEITEM	EvDeleteItem

EV_WM_DRAWITEM	EvDrawItem

EV_WM_MEASUREITEM	EvMeasureItem


TCreatedDC Class

OWL Hierarchy	Inheritance

Header File

dc.h

Description

An abstract TDC class, TCreatedDC serves as the base for DCs that are created and deleted.

See TDC for more information about DC objects.

Public Constructors and Destructor

TCreatedDC(const char far* driver, const char far* device, const char far* output, const DEVMODE far* initData=0);

TCreatedDC(HDC handle TAutoDelete autoDelete);

~TCreatedDC();

Protected Constructor

TCreatedDC();


TCreatedDC Public Constructors and Destructor

See Also	TCreatedDC

Form 1

TCreatedDC(const char far* driver, const char far* device, const char far* output, const DEVMODE far* initData=0);

Form 2

TCreatedDC(HDC handle TAutoDelete autoDelete);

Destructor

~TCreatedDC();

Description

Form 1: Creates a DC object for the device specified by driver (driver name), device (device name), and output (the name of the file or device [port] for the physical output medium). The optional initData argument provides a DEVMODE structure containing device-specific initialization data for this DC. initData must be 0 (the default) if the device is to use any default initializations specified by the user.

Form 2: Creates a DC object using an existing DC.

Destructor

Calls RestoreObjects clears any nonzero OrgXXX data members. If ShouldDelete is true the destructor deletes this DC.


See Also

enum TDC::TAutoDelete

TDC::RestoreObjects

TDC::ShouldDelete

DEVMODE struct


TCreatedDC Protected Constructor

TCreatedDC

Syntax

TCreatedDC();

Description

Creates a device context for the given device. DC objects can be constructed either by borrowing an existing HDC handle or by supplying device and driver information.


TCursor Class

OWL Hierarchy	Inheritance

Header File

gdiobjec.h

Description

TCursor, derived from TGdiBase, represents the GDI cursor object class. TCursor constructors can create cursors from a resource or from explicit information. Because cursors are not real GDI objects, the TCursor destructor overrides the base destructor, ~TGdiBase.

Public Constructors and Destructor

TCursor(HCURSOR handle, TAutoDelete autoDelete = NoAutoDelete);

TCursor(HINSTANCE instance, const TCursor& cursor);

TCursor(HINSTANCE instance, ResId resId);

TCursor(HINSTANCE instance, const TPoint& hotSpot, const TSize& size, void far* andBits, void far* xorBits);

TCursor(const void* resBits uint32 resSize);

TCursor(const ICONINFO* iconInfo);

~TCursor();

Public Member Functions

bool GetIconInfo(ICONINFO* iconInfo) const;

operator HCURSOR() const;

bool operator ==(const TCursor& other) const;


TCursor Public Constructors and Destructor

See Also	TCursor

Form 1

TCursor(HCURSOR handle, TAutoDelete autoDelete = NoAutoDelete);

Form 2

TCursor(HINSTANCE instance, const TCursor& cursor);

Form 3

TCursor(HINSTANCE instance, ResId resId);

Form 4

TCursor(HINSTANCE instance, const TPoint& hotSpot, const TSize& size, void far* andBits, void far* xorBits);

Form 5  (32 bit only)

TCursor(const void* resBits, uint32 resSize);

Form 6  (32 bit only)

TCursor(const ICONINFO* iconInfo);

Destructor

~TCursor();

Description

Form 1: Creates a TCursor object and sets the Handle data member to the given borrowed handle. The ShouldDelete data member defaults to false, ensuring that the borrowed handle will not be deleted when the C++ object is destroyed.

Form 2: Creates a copy of the given cursor object.  The 32bit version (for compiling a Win32 application) uses CopyIcon() and does a cast to get to HICON.

Form 3: Constructs a cursor object from the specified resource ID.

Form 4:Constructs a TCursor object of the specified size at the specified point.

Form 5: (32 bit only) Constructs a TCursor object from the specified resource.

Form 6:  (32 bit only) Creates a TCursor object from the specified ICONINFO structure information.

Destructor

Destroys a TCursor object.


See Also

~TGdiObject

TGdiObject::Handle

TGdiObject::ShouldDelete

TPoint

TSize

ICONINFO struct


TCursor::operator HCURSOR()

TCursor

Syntax

operator HCURSOR() const;

Description

An inline typecasting operator. Converts this cursor's Handle to type HCURSOR (the data type representing the handle to a cursor resource).


TCursor::GetIconInfo

See AlsoTCursor

Syntax

bool GetIconInfo(ICONINFO* iconInfo) const;

Description

<32-bit only>

Retrieves information about this icon and copies it in the given ICONINFO structure. Returns true if the call is successful; otherwise returns false.


See Also

ICONINFO struct


TCursor::operator ==

TCursor

Syntax

bool operator ==(const TCursor& other) const;

Description

Returns true if this cursor equals other; otherwise returns false.


TDC Class

OWL Hierarchy	Inheritance

Header File

dc.h

Description

TDC is the root class for GDI DC wrappers. Each TDC object inherits a Handle from TGdiBase and casts that Handle to an HDC using the HDC operator. Win API functions that take an HDC argument can therefore be called by a corresponding TDC member function without this explicit handle argument.

DC objects can be created directly with TDC constructors, or via the constructors of specialized subclasses (such as TWindowDC, TMemoryDC, TMetaFileDC, TDibDC, and TPrintDC) to get specific behavior. DC objects can be constructed with an already existing and borrowed HDC handle or from scratch by supplying device driver information, as with ::CreateDC. The class TCreateDC takes over much of the creation and deletion work from TDC.

TDC has four handles as protected data members: OrgBrush, OrgPen, OrgFont, and OrgPalette. These handles keep track of the stock GDI objects selected into each DC. As new GDI objects are selected with SelectObject or SelectPalette, these data members store the previous objects. The latter can be restored individually with RestoreBrush, RestorePen, and so on, or they can all be restored with RestoreObjects. When a TDC object is destroyed (via ~TDC::TDC), all the originally selected objects are restored. The data member TDC::ShouldDelete controls the deletion of the TDC object.

Public Constructors and Destructor

TDC(HDC handle);

virtual ~TDC();

Public Member Functions

bool AngleArc(int x, int y, uint32 radius, float startAngle, float sweepAngle);

bool AngleArc(const TPoint& center, uint32 radius, float startAngle, float sweepAngle);

bool Arc(int x1, int y1, int x2, int y2, int x3, int y3, int x4, int y4);

bool Arc(const TRect& r, const TPoint& start, const TPoint& end);

bool BeginPath();

bool BitBlt(int dstX, int dstY, int w, int h, const TDC& srcDC, int srcX, int srcY, uint32 rop=SRCCOPY);

bool BitBlt(const TRect& dst, const TDC& srcDC, const TPoint& src, uint32 rop=SRCCOPY);

bool Chord(int x1, int y1, int x2, int y2, int x3, int y3, int x4, int y4);

bool Chord(const TRect& r, const TPoint& start, const TPoint& end);

bool CloseFigure();

bool DPtoLP(TPoint* points, int count = 1) const;

bool DrawFocusRect(int x1, int x2, int y1, int y2);

bool DrawFocusRect(const TRect& rect);

bool DrawIcon(int x, int y, const TIcon& icon);

bool DrawIcon(const TPoint& point, const TIcon& icon);

virtual bool DrawText(const char far* string, int count, const TRect& r, uint16 format = 0);

bool Ellipse(int x1, int y1, int x2, int y2);

bool Ellipse(const TPoint& p1, const TPoint& p2);

bool Ellipse(const TPoint& point, const TSize& size);

bool Ellipse(const TRect& rect);

bool EndPath();

int EnumFontFamilies(const char far* family, FONTENUMPROC proc, void far* data) const;

int EnumFonts(const char far* faceName, OLDFONTENUMPROC callback, void far* data) const;

int EnumMetaFile(const TMetaFilePict& metaFile, MFENUMPROC callback, void* data) const;

int EnumObjects(uint objectType, GOBJENUMPROC proc, void far* data) const;

int ExcludeClipRect(const TRect& rect);

int ExcludeUpdateRgn(HWND wnd);

bool ExtFloodFill(const TPoint& point, TColor color, uint16 fillType);

virtual bool ExtTextOut(int x, int y, uint16 options, const TRect* r, const char far* string, int count, const int far* dx = 0);

bool ExtTextOut(const TPoint& p, uint16 options, const TRect* r, const char far* string, int count, const int far* dx = 0);

bool FillPath();

bool FillRect(int x1, int y1, int x2, int y2, const TBrush& brush);

bool FillRect(const TRect& rect, const TBrush& brush);

bool FillRgn(const TRegion& region, const TBrush& brush);

bool FlattenPath();

bool FloodFill(const TPoint& point, TColor color);

bool FrameRect(int x1, int x2, int y1, int y2, const TBrush& brush);

bool FrameRect(const TRect& rect, const TBrush& brush);

bool FrameRgn(const TRegion& region, const TBrush& brush, const TPoint& p);

bool GetAspectRatioFilter(TSize& size) const;

TColor GetBkColor() const;

int GetBkMode() const;

bool GetBoundsRect(TRect& bounds, uint16 flags) const;

bool GetBrushOrg(TPoint& point) const;

bool GetCharABCWidths(uint firstChar, uint lastChar, ABC* abc);

bool GetCharWidth(uint firstChar, uint lastChar, int* buffer);

int GetClipBox(TRect& rect) const;

TRect GetClipBox() const;

bool GetClipRgn(TRegion& region) const;

HANDLE GetCurrentObject(uint objectType) const;

bool GetCurrentPosition(TPoint& point) const;

bool GetDCOrg(TPoint& point) const;

virtual int GetDeviceCaps(int index) const;

bool GetDIBits(const TBitmap& bitmap, uint16 startScan, uint16 numScans, void HUGE* bits, const BITMAPINFO far& info, uint16 usage)

bool GetDIBits(const TBitmap& bitmap, TDib& dib);

uint32 GetFontData(uint32 table, uint32 offset, void* buffer, long data);

uint32 GetGlyphOutline(uint chr, uint format, GLYPHMETRICS far& gm, uint32 buffSize, void far* buffer, const MAT2 far& mat2);

int GetKerningPairs(int pairs, KERNINGPAIR far* krnPair);

int GetMapMode() const;

TColor GetNearestColor(TColor Color) const;

uint32 GetOutlineTextMetrics(uint data, OUTLINETEXTMETRIC far& otm);

uint16 GetOutlineTextMetrics(uint data, OUTLINETEXTMETRIC far& otm);

TColor GetPixel(int x, int y) const;

TColor GetPixel(const TPoint& point) const;

int GetPolyFillMode() const;

int GetROP2() const;

int GetStretchBltMode() const;

uint GetSystemPaletteEntries(int start, int num, PALETTEENTRY far* entries) const;

uint GetSystemPaletteUse() const;

bool GetTabbedTextExtent(const char far* string, int stringLen, int numPositions, const int far* positions, TSize& size) const;

TSize GetTabbedTextExtent(const char far* string, int stringLen, int numPositions, const int far* positions) const;

uint GetTextAlign() const;

int GetTextCharacterExtra() const;

TColor GetTextColor() const;

bool GetTextExtent(const char far* string, int stringLen, TSize& size);

TSize GetTextExtent(const char far* string, int stringLen);

int GetTextFace(int count, char far* facename) const;

bool GetTextMetrics(TEXTMETRIC far& metrics) const;

bool GetViewportExt(TSize& extent) const;

TSize GetViewportExt() const;

bool GetViewportOrg(TPoint& point) const;

TPoint GetViewportOrg() const;

bool GetWindowExt(TSize& extent) const;

TSize GetWindowExt() const;

bool GetWindowOrg(TPoint& point) const;

TPoint GetWindowOrg() const;

virtual bool GrayString(const TBrush& brush, GRAYSTRINGPROC outputFunc, const char far* string, int count, const TRect& r);

operator HDC() const{return Handle;}

int IntersectClipRect(const TRect& rect);

bool InvertRect(int x1, int x2, int y1, int y2);

bool InvertRect(const TRect& rect);

bool InvertRgn(const TRegion& region);

bool LineTo(int x, int y);

bool LineTo(const TPoint& point);

bool LPtoDP(TPoint* points, int count = 1) const;

bool MaskBlt(const TRect& dst, const TDC& srcDC, const TPoint& src, const TBitmap& maskBm, const TPoint& maskPos, uint32 rop);

bool ModifyWorldTransform(XFORM far& xform, uint32 mode);

bool MoveTo(int x, int y);

bool MoveTo(const TPoint& point);

bool MoveTo(const TPoint& point, TPoint& oldPoint);

int OffsetClipRgn(const TPoint& delta);

virtual bool OffsetViewportOrg(const TPoint& delta, TPoint* oldOrg = 0);

bool OffsetWindowOrg(const TPoint& delta, TPoint* oldOrg = 0);

void OWLFastWindowFrame(TBrush& brush, TRect& rect, int xWidth, int yWidth);

bool PaintRgn(const TRegion& region);

bool PatBlt(int x, int y, int w, int h, uint32 rop=PATCOPY);

bool PatBlt(const TRect& dst, uint32 rop=PATCOPY);

HRGN PathToRegion();

bool Pie(int x1, int y1, int x2, int y2, int x3, int y3, int x4, int y4);

bool Pie(const TRect& rect, const TPoint& start, const TPoint& end);

bool PlayMetaFile(const TMetaFilePict& metaFile);

void PlayMetaFileRecord(HANDLETABLE far& Handletable, METARECORD far& metaRecord, int count);

bool PlgBlt(const TPoint& dst, const TDC& srcDC, const TRect& src, const TBitmap& maskBm, const TPoint& maskPos, uint32 rop=SRCCOPY);

bool PolyBezier(const TPoint* points, int count);

bool PolyBezierTo(const TPoint* points, int count);

bool PolyDraw(const TPoint* points, uint8* types, int count);

bool Polygon(const TPoint* points, int count);

bool Polyline(const TPoint* points, int count);

bool PolylineTo(const TPoint* points, int count);

bool PolyPolygon(const TPoint* points, const int* PolyCounts, int count);

bool PolyPolyline(const TPoint* points, const int* PolyCounts, int count);

bool PtVisible(const TPoint& point) const;

int RealizePalette();

bool Rectangle(int x1, int y1, int x2, int y2);

bool Rectangle(const TPoint& p1, const TPoint& p2);

bool Rectangle(const TPoint& point, const TSize& s);

bool Rectangle(const TRect& rect);

bool RectVisible(const TRect& rect) const;

virtual bool ResetDC(DEVMODE far& devMode);

void RestoreBrush();

virtual bool RestoreDC(int savedDC = -1);

virtual void RestoreFont();

void RestoreObjects();

void RestorePalette();

void RestorePen();

void RestoreTextBrush();

bool RoundRect(int x1, int y1, int x2, int y2, int x3, int y3);

bool RoundRect(const TPoint& p1, const TPoint& p2, const TPoint& rad);

bool RoundRect(const TPoint& p, const TSize& s, const TPoint& rad);

bool RoundRect(const TRect& rect, const TPoint& rad);

virtual int SaveDC() const;

virtual bool ScaleViewportExt(int xNum, int xDenom, int yNum, int yDenom, TSize* oldExtent = 0);

virtual bool ScaleWindowExt(int xNum, int xDenom, int yNum, int yDenom, TSize* oldExtent = 0);

bool ScrollDC(int x, int y, const TRect& scroll, const TRect& clip, TRegion& updateRgn, TRect& updateRect);

bool ScrollDC(const TPoint& delta, const TRect& scroll, const TRect& clip, TRegion& updateRgn, TRect& updateRect);

bool SelectClipPath(int mode);

int SelectClipRgn(const TRegion& region);

void SelectObject(const TBrush& brush);

void SelectObject(const TPen& pen);

virtual void SelectObject(const TFont& font);

void SelectObject(const TPalette& palette, bool forceBackground = false);

virtual void SelectStockObject(int index);

virtual TColor SetBkColor(TColor color);

int SetBkMode(int mode);

uint SetBoundsRect(TRect& bounds, uint flags);

bool SetBrushOrg(const TPoint& origin, TPoint* oldOrg = 0);

bool SetDIBits(TBitmap& bitmap, uint16 startScan, uint16 numScans, const void HUGE* bits, const BITMAPINFO far& Info, uint16 usage);

bool SetDIBits(TBitmap& Bitmap, const TDib& dib);

bool SetDIBitsToDevice(const TRect& dst, const TPoint& src, uint16 startScan, uint16 numScans, const void HUGE* bits, const BITMAPINFO far& bitsInfo, uint16 usage);

bool SetDIBitsToDevice(const TRect& dst, const TPoint& src, const TDib& dib);

virtual int SetMapMode(int mode);

uint32 SetMapperFlags(uint32 flag);

bool SetMiterLimit(float newLimit, float* oldLimit = 0);

TColor SetPixel(int x, int y, TColor color);

TColor SetPixel(const TPoint& p, TColor color);

int SetPolyFillMode(int mode);

int SetROP2(int mode);

int SetStretchBltMode(int mode);

int SetSystemPaletteUse(int usage);

uint SetTextAlign(uint flags);

int SetTextCharacterExtra(int extra);

virtual TColor SetTextColor(TColor color);

bool SetTextJustification(int breakExtra, int breakCount);

virtual bool SetViewportExt(const TSize& extent, TSize* oldExtent = 0);

virtual bool SetViewportOrg(const TPoint& origin, TPoint* oldOrg = 0);

virtual bool SetWindowExt(const TSize& extent, TSize* oldExtent = 0);

bool SetWindowOrg(const TPoint& origin, TPoint* oldOrg = 0);

bool SetWorldTransform(XFORM far& xform);

bool StretchBlt(int dstX, int dstY, int dstW, int dstH, const TDC& srcDC, int srcX, int srcY, int srcW, int srcH, uint32 rop=SRCCOPY);

bool StretchBlt(const TRect& dst, const TDC& srcDC, const TRect& src, uint32 rop=SRCCOPY);

bool StretchDIBits(const TRect& dst, const TRect& src, const void HUGE* bits, const BITMAPINFO far& bitsInfo, uint16 usage, uint32 rop=SRCCOPY);

bool StretchDIBits(const TRect& dst, const TRect& src, const TDib& dib, uint32 rop=SRCCOPY);

bool StrokeAndFillPath();

bool StrokePath();

bool TabbedTextOut(const TPoint& p, const char far* string, int count, int numPositions, const int far* positions, int tabOrigin);

virtual bool TabbedTextOut(const TPoint& p, const char far* string, int count, int numPositions, const int far* positions, int tabOrigin, TSize& size);

virtual bool TextOut(int x, int y, const char far* string, int count = -1);

bool TextOut(const TPoint& p, const char far* string, int count = -1);

bool TextRect(int x1, int y1, int x2, int y2);

bool TextRect(const TRect& rect);

bool TextRect(int x1, int y1, int x2, int y2, TColor color);

bool TextRect(const TRect rect, TColor color);

void UpdateColors();

bool WidenPath();

Protected Constructor

TDC();

TDC(HDC handle, TAutoDelete AutoDelete);

Protected Data Members

TGDIBase::Handle;

HBRUSH OrgBrush;

HFONT OrgFont;

HPALETTE OrgPalette;

HPEN OrgPen;

HBRUSH OrgTextBrush;

TGdiBase::ShouldDelete;

Protected Member Functions

TGdiBase::CheckValid(uint resId=IDS_GDIFAILURE)

static void CheckValid(HANDLE handle, uint resId=IDS_GDIFAILURE)

virtual HDC GetAttributeHDC() const;

HDC GetHDC() const;

void Init();


TDC Public Constructors and Destructor

See Also	TDC

Syntax

TDC(HDC handle);

Description

Creates a DC object "borrowing" the handle of an existing DC. The Handle data member is set to the given handle argument.

Destructor

virtual ~TDC();

Calls RestoreObjects.


See Also

TCreatedDC

TDC::RestoreObjects

TDC::ShouldDelete


TDC::AngleArc

See Also	TDC

Form 1

bool AngleArc(int x, int y, uint32 radius, float startAngle, float sweepAngle);

Form 2

bool AngleArc(const TPoint& center, uint32 radius, float startAngle, float sweepAngle);

Description

32-bit only. Draws a line segment and an arc on this DC using the currently selected pen object. The line is drawn from the current position to the beginning of the arc. The arc is that part of the circle (with the center at logical coordinates (x, y) and positive radius, radius) starting at startAngle and ending at (startAngle + sweepAngle). Both angles are measured in degrees, counterclockwise from the x-axis (the default arc direction). The arc might appear to be elliptical, depending on the current transformation and mapping mode. AngleArc returns true if the figure is drawn successfully; otherwise, it returns false. If successful, the current position is moved to the end point of the arc.


See Also

TDC::Arc

TPoint


TDC::Arc

See Also	TDC

Form 1

bool Arc(int x1, int y1, int x2, int y2, int x3, int y3, int x4, int y4);

Form 2

bool Arc(const TRect& r, const TPoint& start, const TPoint& end);

Description

Draws an elliptical arc on this DC using the currently selected pen object. The center of the arc is the center of the bounding rectangle, specified either by (x1, y1)/(x2, y2) or by the rectangle r. The starting/ending points of the arc are specified either by (x3, y3)/(x4, y4) or by the points start and end. All points are specified in logical coordinates. Arc returns true if the arc is drawn successfully; otherwise, it returns false. The current position is neither used nor altered by this call. The drawing direction default is counterclockwise.


See Also

TDC::AngleArc

TPoint

TRect


TDC::BeginPath

See Also	TDC

Syntax

bool BeginPath();

Description

32-bit only. Opens a new path bracket for this DC and discards any previous paths from this DC. Once a path bracket is open, an application can start calling draw functions on this DC to define the points that lie within that path. The draw functions that define points in a path are the following TDC members: AngleArc, Arc, Chord, CloseFigure, Ellipse, ExtTextOut, LineTo, MoveToEx, Pie, PolyBezier, PolyBezierTo, PolyDraw, Polygon, Polyline, PolylineTo, PolyPolygon, PolyPolyline, Rectangle, RoundRect, and TextOut.

A path bracket can be closed by calling TDC::EndPath.

BeginPath returns true if the call is successful; otherwise, it returns false.


See Also

TDC::FillPath

TDC::EndPath

TDC::PathToRegion

TDC::StrokePath

TDC::StrokeandFillPath

TDC::WidenPath


TDC::BitBlt

See Also	TDC

Form 1

bool BitBlt(int dstX, int dstY, int w, int h, const TDC& srcDC, int srcX, int srcY, uint32 rop=SRCCOPY);

Form 2

bool BitBlt(const TRect& dst, const TDC& srcDC, const TPoint& src, uint32 rop=SRCCOPY);

Description

Performs a bit-block transfer from srcDc (the given source DC) to this DC (the destination DC). Color bits are copied from a source rectangle to a destination rectangle. The location of the source rectangle is specified either by its upper left-corner logical coordinates (srcX, srcY), or by the TPoint object, src. The destination rectangle can be specified either by its upper left-corner logical coordinates (dstX, dstY), width w, and height h, or by the TRect object, dst. The destination rectangle has the same width and height as the source. The rop argument specifies the raster operation used to combine the color data for each pixel. See TDC::MaskBlt for a detailed list of rop codes.

When recording an enhanced metafile, an error occurs if the source DC identifies the enhanced metafile DC.


See Also

TPoint

TRect


TDC::Chord

See Also	TDC

Form 1

bool Chord(int x1, int y1, int x2, int y2, int x3, int y3, int x4, int y4);

Form 2

bool Chord(const TRect& r, const TPoint& start, const TPoint& end);

Description

Draws and fills a chord (a region bounded by the intersection of an ellipse and a line segment) on this DC using the currently selected pen and brush objects. The ellipse is specified by a bounding rectangle given either by (x1, y1)/(x2, y2) or by the rectangle R. The starting/ending points of the chord are specified either by (x3, y3)/(x4, y4) or by the points Start and End. Chord returns true if the call is successful; otherwise, it returns false. The current position is neither used nor altered by this call.


See Also

TDC::Arc

TPoint

TRect


TDC::Figure
TDC::CloseFigure

See Also	TDC

Syntax

bool CloseFigure();

Description

32-bit only. Closes an open figure in this DC's open path bracket by drawing a line from the current position to the first point of the figure (usually the point specified by the most recent TDC::MoveTo call), and connecting the lines using the current join style for this DC. If you close a figure with TDC::LineTo instead of with CloseFigure, end caps (instead of a join) are used to create the corner. The call fails if there is no open path bracket on this DC. Any line or curve added to the path after a CloseFigure call starts a new figure. A figure in a path remains open until it is explicitly closed with CloseFigure even if its current position and start point happen to coincide.

CloseFigure returns true if the call is successful; otherwise, it returns false.


See Also

TDC::BeginPath

TDC::EndPath


TDC::DPtoLP

See Also	TDC

Syntax

bool DPtoLP(TPoint* points, int count = 1) const;

Description

Converts each of the count points in the points array from device points to logical points. The conversion depends on this DC's current mapping mode and the settings of its window and viewport origins and extents. DPtoLP returns true if the call is successful; otherwise, it returns false.


See Also

TDC::LPtoDP

TPoint


TDC::DrawFocusRect

See Also	TDC

Form 1

bool DrawFocusRect(int x1, int x2, int y1, int y2);

Form 2

bool DrawFocusRect(const TRect& rect);

Description

Draws the given rectangle on this DC in the style used to indicate focus. Calling the function a second time with the same rect argument will remove the rectangle from the display. A rectangle drawn with DrawFocusRect cannot be scolled. DrawFocusRect returns true if the call is successful; otherwise, it returns false.


See Also

TRect


TDC::DrawIcon

See Also	TDC

Form 1

bool DrawIcon(int x, int y, const TIcon& icon);

Form 2

bool DrawIcon(const TPoint& point, const TIcon& icon);

Description

Draws the given icon on this DC. The upper left corner of the drawn icon can be specified by x- and y-coordinates or by the point argument. DrawIcon returns true if the call is successful; otherwise, it returns false.


See Also

TIcon


TDC::DrawText

See Also	TDC

Syntax

virtual bool DrawText(const char far* string, int count, const TRect& r, uint16 format = 0);

Description

Formats and draws in the given rectangle, r, up to count characters of the null-terminated string using the current font for this DC. If count is -1, the whole string is written. The rectangle must be specified in logical units. Formatting is controlled with the format argument, which can be various combinations of the following values:

Value	Meaning

DT_BOTTOM	Specifies bottom-justified text. This value must be combined (bitwise OR'd) with DT_SINGLELINE.

DT_CALCRECT	Determines the width and height of the rectangle. If there are multiple lines of text, DrawText uses the width of r (the rectangle argument) and extends the base of the rectangle to bound the last line of text. If there is only one line of text, DrawText uses a modified value for the right side of r so that it bounds the last character in the line. In both cases, DrawText returns the height of the formatted text but does not draw the text.

DT_CENTER	Centers text horizontally.

DT_EXPANDTABS	Expands tab characters. The default number of characters per tab is eight.

DT_EXTERNALLEADING	Includes the font external leading in line height. Normally, external leading is not included in the height of a line of text.

DT_LEFT	Aligns text flush-left.

DT_NOCLIP	Draws without clipping. DrawText is somewhat faster when DT_NOCLIP is used.

DT_NOPREFIX	Turns off processing of prefix characters. Normally, DrawText interprets the prefix character & as a directive to underscore the character that follows, and the prefix characters && as a directive to print a single &. By specifying DT_NOPREFIX, this processing is turned off.

DT_RIGHT	Aligns text flush-right.

DT_SINGLELINE	Specifies single line only. Carriage returns and linefeeds do not break the line.

DT_TABSTOP	Sets tab stops. Bits 15-8 (the high-order byte of the low-order word) of the format argument are the number of characters for each tab. The default number of characters per tab is eight.

DT_TOP	Specifies top-justified text (single line only).

DT_VCENTER	Specifies vertically centered text (single line only).

DT_WORDBREAK	Specifies word breaking. Lines are automatically broken between words if a word would extend past the edge of the rectangle specified by r. A carriage return/line sequence will also break the line.

Note that the DT_CALCRECT, DT_EXTERNALLEADING, DT_INTERNAL, DT_NOCLIP, and DT_NOPREFIX values cannot be used with the DT_TABSTOP value.

DrawText uses this DC's currently selected font, text color, and background color to draw the text. Unless the DT_NOCLIP format is used, DrawText clips the text so that it does not appear outside the given rectangle. All formatting is assumed to have multiple lines unless the DT_SINGLELINE format is given.

If the selected font is too large for the specified rectangle, DrawText does not attempt to substitute a smaller font.

If successful, DrawText returns TRUE; otherwise, returns FALSE.


See Also

TDC::GrayString

TDC::TabbedTextOut

TDC::TextOut

TRect


TDC::Ellipse

See Also	TDC

Form 1

bool Ellipse(int x1, int y1, int x2, int y2);

Form 2

bool Ellipse(const TPoint& p1, const TPoint& p2);

Form 3

bool Ellipse(const TPoint& point, const TSize& size);

Form 4

bool Ellipse(const TRect& rect);

Description

Draws and fills an ellipse on this DC using the currently selected pen and brush objects. The center of the ellipse is the center of the bounding rectangle specified either by (x1, y1)/(x2, y2) or by the rect argument. Ellipse returns true if the call is successful; otherwise, it returns false. The current position is neither used nor altered by this call.


See Also

TDC::Arc

TPoint

TRect

TSize


TDC::EndPath

See Also	TDC

Syntax

bool EndPath();

Description

32-bit only. Closes the path bracket and selects the path it defines into this DC. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::BeginPath

TDC::CloseFigure


TDC::EnumFontFamilies

See Also	TDC

Syntax

int EnumFontFamilies(const char far* family, FONTENUMPROC proc, void far* data) const;

Description

Enumerates the fonts available to this DC in the font family specified by family. The given application-defined callback proc is called for each font in the family or until proc returns 0, and is defined as:

typedef int (CALLBACK* FONTENUMPROC)(CONST LOGFONT *, CONST TEXTMETRIC *, DWORD, LPARAM);

data lets you pass both application-specific data and font data to proc. If successful, the call returns the last value returned by proc.


See Also

TDC::EnumFonts

LOGFONT struct

TEXTMETRIC struct


TDC::EnumFonts

See Also	TDC

Syntax

int EnumFonts(const char far* faceName, OLDFONTENUMPROC callback, void far* data) const;

Description

Enumerates the fonts available on this DC for the given faceName. The font type, LOGFONT, and TEXTMETRIC data retrieved for each available font is passed to the user-defined callback function together with any optional, user-supplied data placed in the data buffer. The callback function can process this data in any way desired. Enumeration continues until there are no more fonts or until the callback function returns 0. If faceName is 0, EnumFonts randomly selects and enumerates one font of each available typeface. EnumFonts returns the last value returned by the callback function. Note that OLDFONTENUMPROC is defined as FONTENUMPROC for Win32 only. FONTENUMPROC is a pointer to a user-defined function and has the following prototype:

int CALLBACK EnumFontsProc(LOGFONT *lplf, TEXTMETRIC *lptm, uint32 dwType, LPARAM lpData);

where dwType specifies one of the following font types: DEVICE_FONTTYPE, RASTER_FONTTYPE, or TRUETYPE_FONTTYPE.


See Also

TDC::EnumFontFamilies

LOGFONT struct

TEXTMETRIC struct


TDC::EnumMetaFile

TDC

Syntax

int EnumMetaFile(const TMetaFilePict& metaFile, MFENUMPROC callback, void* data) const;

Description

Enumerates the GDI calls within the given metaFile. Each such call is retrieved and passed to the given callback function, together with any client data from data, until all calls have been processed or a callback function returns 0. MFENUMPROC is defined as:

typedef int (CALLBACK* MFENUMPROC)(HDC, HANDLETABLE FAR*, METARECORD FAR*, int, LPARAM);


See Also

TDC::PlayMetaFile

METARECORD struct


TDC::EnumObjects

TDC

Syntax

int EnumObjects(uint objectType, GOBJENUMPROC proc, void far* data) const;

Description

Enumerates the pen or brush objects available for this DC. The parameter objectType can be either OBJ_BRUSH or OBJ_PEN. For each pen or brush found, proc, a user-defined callback function, is called until there are no more objects found or the callback function returns 0. proc is defined as:

typedef int (CALLBACK* GOBJENUMPROC)(LPVOID, LPARAM);

Parameter data specifies an application-defined value that is passed to proc.


TDC::ExcludeClipRect

See Also	TDC

Syntax

int ExcludeClipRect(const TRect& rect);

Description

Creates a new clipping region for this DC. This new region consists of the current clipping region minus the given rectangle, rect. The return value indicates the new clipping region's type as follows:

Region	Meaning

COMPLEXREGION	Clipping Region has overlapping borders.

ERROR	Invalid DC.

NULLREGION	Clipping region is empty.

SIMPLEREGION	Clipping region has no overlapping borders.


See Also

TDC::GetClipBox

TRect


TDC::ExcludeUpdateRgn

TDC

Syntax

int ExcludeUpdateRgn(HWND wnd);

Description

Prevents drawing within invalid areas of a window by excluding an updated region of this DC's window from its clipping region. The return value indicates the resulting clipping region's type as follows:

Region	Meaning

COMPLEXREGION	Clipping Region has overlapping borders.

ERROR	Invalid DC.

NULLREGION	Clipping region is empty.

SIMPLEREGION	Clipping region has no overlapping borders.


TDC::ExtFloodFill

See Also	TDC

Syntax

bool ExtFloodFill(const TPoint& point, TColor color, uint16 fillType);

Description

Fills an area on this DC starting at point and using the currently selected brush object. The color argument specifies the color of the boundary or of the region to be filled. The fillType argument specifies the type of fill, as follows:

FLOODFILLBORDER	The fill region is bounded by the given color. This style coincides with the filling method used by FloodFill.

FLOODFILLSURFACE	The fill region is defined by the given color. Filling continues outward in all directions as long as this color is encountered. Use this style when filling regions with multicolored borders.

Not every device supports ExtFloodFill, so applications should test first with TDC::GetDeviceCaps.

ExtFloodFill returns true if the call is successful; otherwise, it returns false.


See Also

TDC::FloodFill

TDC::GetDeviceCaps

TColor

TPoint


TDC::ExtTextOut

See Also	TDC

Form 1

virtual bool ExtTextOut(int x, int y, uint16 options, const TRect* r, const char far* string, int count, const int far* dx = 0);

Form 2

bool ExtTextOut(const TPoint& p, uint16 options, const TRect* r, const char far* string, int count, const int far* dx = 0);

Description

Draws up to count characters of the given null-terminated string in the current font on this DC. If count is -1, the whole string is written.

An optional rectangle r can be specified for clipping, opaquing, or both, as determined by the options value. If options is set to ETO_CLIPPED, the rectangle is used for clipping the drawn text. If options is set to ETO_OPAQUE, the current background color is used to fill the rectangle. Both options can be used if ETO_CLIPPED is OR'd with ETO_OPAQUE.

The (x, y) orparguments specify the logical coordinates of the reference point that is used to align the first character. The current text-alignment mode can be inspected with TDC::GetTextAlign and changed with TDC::SetTextAlign. By default, the current position is neither used nor altered by ExtTextOut. However, if the align mode is set to TA_UPDATECP, ExtTextOut ignores the reference point argument(s) and uses or updates the current position as the reference point.

The dx argument is an optional array of values used to set the distances between the origins (upper left corners) of adjacent character cells. For example, dx[i] represents the number of logical units separating the origins of character cells i and i+1. If dx is 0, ExtTextOut uses the default inter-character spacings.

ExtTextOut returns true if the call is successful; otherwise, it returns false.


See Also

TDC::TextOut

TDC::GetTextAlign

TDC::TabbedTextOut

TPoint

TRect


TDC::FillPath

See Also	TDC

Syntax

bool FillPath();

Description

32-bit only. Closes any open figures in the current path of this DC and fills the path's interior using the current brush and polygon fill mode. After filling the interior, FillPath discards the path from this DC.

FillPath returns true if the call is successful; otherwise, it returns false.


See Also

TDC::BeginPath

TDC::CloseFigure

TDC::StrokePath

TDC::StrokeAndFillPath

TDC::SetPolyFillMode


TDC::FillRect

See Also	TDC

Form 1

bool FillRect(int x1, int y1, int x2, int y2, const TBrush& brush);

Form 2

bool FillRect(const TRect& rect, const TBrush& brush);

Description

Fills the given rectangle on this DC using the specified brush. The fill covers the left and top borders but excludes the right and bottom borders. FillRect returns true if the call is successful; otherwise, it returns false.


See Also

TBrush

TRect


TDC::FillRgn

See Also	TDC

Syntax

bool FillRgn(const TRegion& region, const TBrush& brush);

Description

Fills the given region on this DC using the specified brush. FillRgn returns true if the call is successful; otherwise, it returns false.


See Also

TDC::InvertRgn

TDC::PaintRgn

TBrush

TRegion


TDC::FlattenPath

See Also	TDC

Syntax

bool FlattenPath();

Description

32-bit only. Transforms any curves in the currently selected path of this DC. All such curves are changed to sequences of linear segments. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::WidenPath

TDC::BeginPath


TDC::FloodFill

See Also	TDC

Syntax

bool FloodFill(const TPoint& point, TColor color);

Description

Fills an area on this DC starting at point and using the currently selected brush object. The color argument specifies the color of the boundary or of the area to be filled. Returns true if the call is successful; otherwise, returns false. FloodFill is maintained in the WIN32 API for compatibility with earlier APIs. New WIN32 applications should use TDC::ExtFloodFill.


See Also

TDC::ExtFloodFill

TColor

TPoint


TDC::FrameRect

See Also	TDC

Form 1

bool FrameRect(int x1, int x2, int y1, int y2, const TBrush& brush);

Form 2

bool FrameRect(const TRect& rect, const TBrush& brush);

Description

Draws a border on this DC around the given rectangle, rect, using the given brush, brush. The height and width of the border is one logical unit. Returns true if the call is successful; otherwise, it returns false.


See Also

TBrush

TRect


TDC::FrameRgn

See Also	TDC

Syntax

bool FrameRgn(const TRegion& region, const TBrush& brush, const TPoint& p);

Description

Draws a border on this DC around the given region, region, using the given brush, brush. The width and height of the border is specified by the p argument. Returns true if the call is successful; otherwise, returns false.


See Also

TBrush

TRegion


TDC::GetAspectRatioFilter

See Also	TDC

Syntax

bool GetAspectRatioFilter(TSize& size) const;

Description

Retrieves the setting of the current aspect-ratio filter for this DC.


See Also

TSize


TDC::GetBkColor

See Also	TDC

Syntax

TColor GetBkColor() const;

Description

Returns the current background color of this DC.


See Also

TDC::SetBkColor

TColor


TDC::GetBkMode

See Also	TDC

Syntax

int GetBkMode() const;

Description

Returns the background mode of this DC, either OPAQUE or TRANSPARENT.


See Also

TDC::SetBkMode


TDC::GetBoundsRect

See Also	TDC

Syntax

bool GetBoundsRect(TRect& bounds, uint16 flags) const;

Description

Reports in bounds the current accumulated bounding rectangle of this DC or of the Windows manager, depending on the value of flags. Returns true if the call is successful; otherwise, returns false.

The flags argument can be DCB_RESET or DCB_WINDOWMGR or both. The flags value work as follows:

DCB_RESET	Forces the bounding rectangle to be cleared after being set in bounds.

DCB_WINDOWMGR	Reports the Windows current bounding rectangle rather than that of this DC.

There are two bounding-rectangle accumulations, one for Windows and one for the application. GetBoundsRect returns screen coordinates for the Windows bounds, and logical units for the application bounds. The Windows accumulated bounds can be queried by an application but not altered. The application can both query and alter the DC's accumulated bounds.


See Also

TDC::SetBoundsRect

TRect


TDC::GetBrushOrg

See Also	TDC

Syntax

bool GetBrushOrg(TPoint& point) const;

Description

Places in point the current brush origin of this DC. Returns true if successful; otherwise, returns false.


See Also

TPoint


TDC::GetCharABCWidths

See Also	TDC

Syntax

bool GetCharABCWidths(uint firstChar, uint lastChar, ABC* abc);

Description

Retrieves the widths of consecutive characters in the range firstChar to lastChar from the current TrueType font of this DC. The widths are reported in the array abc of ABC structures. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::GetCharWidth

ABC struct


TDC::GetCharWidth

See Also	TDC

Syntax

bool GetCharWidth(uint firstChar, uint lastChar, int* buffer);

Description

Retrieves the widths in logical units for a consecutive sequence of characters in the current font for this DC. The sequence is specified by the inclusive range, firstChar to lastChar, and the widths are copied to the given buffer. If a character in the range is not represented in the current font, the width of the default character is assigned. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::GetCharABCWidths


TDC::GetClipBox

See Also	TDC

Form 1

int GetClipBox(TRect& rect) const;

Form 2

TRect GetClipBox() const;

Description

Places the current clip box size of this DC in rect. The clip box is defined as the smallest rectangle bounding the current clipping boundary. The return value indicates the clipping region's type as follows:

Region	Meaning

COMPLEXREGION	Clipping Region has overlapping borders.

ERROR	Invalid DC.

NULLREGION	Clipping region is empty.

SIMPLEREGION	Clipping region has no overlapping borders.


See Also

TDC::ExcludeClipRect

TRect


TDC::GetClipRgn

See Also	TDC

Syntax

bool GetClipRgn(TRegion& region) const;

Description

Retrieves this DC's current clip-region and, if successful, places a copy of it in the region argument. You can alter this copy without affecting the current clip-region. Returns true if the call is successful; otherwise, returns false.


See Also

TRegion


TDC::GetCurrentObject

TDC

Syntax

HANDLE GetCurrentObject(uint objectType) const;

Description

Returns a handle to the currently selected object of the given objectType associated with this DC. Returns 0 if the call fails. objectType can be OBJ_PEN, OBJ_BRUSH, OBJ_PAL, OBJ_FONT, or OBJ_BITMAP.


TDC::GetCurrentPosition

See Also	TDC

Syntax

bool GetCurrentPosition(TPoint& point) const;

Description

Reports in point the logical coordinates of this DC's current position. Returns true if the call is successful; otherwise, returns false.


See Also

TPoint


TDC::GetDCOrg

See Also	TDC

Syntax

bool GetDCOrg(TPoint& point) const;

Description

Obtains the final translation origin for this device context and places the value in point. This value specifies the offset used to translate device coordinates to client coordinates for points in an application window. Returns true if the call is successful; otherwise, returns false.


See Also

TPoint


TDC::GetDeviceCaps

TDC

Syntax

virtual int GetDeviceCaps(int index) const;

Description

Used under WIN3.1 or later, GetDeviceCaps returns capability information about this DC. The index argument specifies the type of information required.


TDC::GetDIBits

See Also	TDC

Form 1

bool GetDIBits(const TBitmap& bitmap, uint16 startScan, uint16 numScans, void HUGE* bits, const BITMAPINFO far& info, uint16 usage);

Form 2

bool GetDIBits(const TBitmap& bitmap, TDib& dib);

Description

The first version retrieves some or all of the bits from the given bitmap on this DC and copies them to the bits buffer using the DIB (device-independent bitmap) format specified by the BITMAPINFO argument, info. numScan scanlines of the bitmap are retrieved, starting at scan line startScan. The usage argument determines the format of the bmiColors member of the BITMAPINFO structure, according to the following table:

Value	Meaning

DIB_PAL_COLORS	The color table is an array of 16-bit indexes into the current logical palette.

DIB_RGB_COLORS	The color table contains literal RGB values.

DIB_PAL_INDICES	There is no color table for this bitmap. The DIB bits consist of indexes into the system palette. No color translation occurs. Only the BITMAPINFOHEADER portion of BITMAPINFO is filled in.

In the second version of GetDIBits, the bits are retrieved from bitmap and placed in the dib.Bits data member of the given TDib argument. The BITMAPINFO argument is supplied from dib.info.

GetDIBits returns true if the call is successful; otherwise, it returns false.


See Also

TDC::SetDIBits

TBitmap

TDib

BITMAPINFO struct


TDC::GetFontData

TDC

Syntax

uint32 GetFontData(uint32 table, uint32 offset, void* buffer, long data);

Description

Retrieves font-metric information from a scalable TrueType font file (specified by table and starting at offset into this table) and places it in the given buffer. data specifies the size in bytes of the data to be retrieved. If the call is successful, it returns the number of bytes set in buffer; otherwise, -1 is returned.


TDC::GetGlyphOutline

See Also	TDC

Syntax

uint32 GetGlyphOutline (uint chr, uint format, GLYPHMETRICS far& gm, uint32 buffSize, voidfar* buffer, const MAT2 far& mat2);

Description

Retrieves TrueType metric and other data for the given character, chr, on this DC and places it in gm and buffer. The format argument specifies the format of the retrieved data as indicated in the following table. (A value of 0 simply fills in the GLYPHMETRICS structure but does not return glyph-outline data.)

Value	Meaning

1	Retrieves the glyph bitmap.

2	Retrieves the curve data points in the rasterizer's native format and uses the font's design units. With this value of format, the mat2 transformation argument is ignored.

The gm argument specifies the GLYPHMETRICS structure that describes the placement of the glyph in the character cell. buffSize specifies the size of buffer that receives data about the outline character. If either buffSize or buffer is 0, GetGlyphOutline returns the required buffer size. Applications can rotate characters retrieved in bitmap format (format = 1) by specifying a 2 x 2 transformation matrix via the mat2 argument.

GetGlyphOutline returns a positive number if the call is successful; otherwise, it returns GDI_ERROR.


See Also

TDC::GetOutlineTextMetrics

GLYPHMETRICS struct


TDC::GetKerningPairs

See Also	TDC

Syntax

int GetKerningPairs(int pairs, KERNINGPAIR far* krnPair);

Description

Retrieves kerning pairs for the current font of this DC up to the number specified in pairs and copies them into the krnPair array of KERNINGPAIR structures. If successful, the function returns the actual number of pairs retrieved. If the font has more than pairs kerning pairs, the call fails and returns 0. The krnPair array must allow for at least pairs KERNINGPAIR structures. If krnPair is set to 0, GetKerningPairs returns the total number of kerning pairs for the current font.


See Also

KERNINGPAIR struct


TDC::GetMapMode

See Also	TDC

Syntax

int GetMapMode() const;

Description

If successful, returns the current window mapping mode of this DC; otherwise, returns 0. The mapping mode defines how logical coordinates are mapped to device coordinates. It also controls the orientation of the device's x- and y-axes. The mode values are shown in the following table:

Value	Meaning

MM_ANISOTROPIC	Logical units are mapped to arbitrary units with arbitrarily scaled axes. SetWindowExtEx and SetViewportExtEx  must be used to specify the desired units, orientation, and scaling.

MM_HIENGLISH	Each logical unit is mapped to 0.001 inch. Positive x is to the right; positive y is at the top.

MM_HIMETRIC	Each logical unit is mapped to 0.01 millimeter. Positive x is to the right; positive y is at the top.

MM_ISOTROPIC	Logical units are mapped to arbitrary units with equally scaled axes; that is, one unit along the x-axis is equal to one unit along the y-axis. SetWindowExtEx and SetViewportExtEx must be used to specify the desired units and the orientation of the axes. GDI makes adjustments as necessary to ensure that the x and y units remain the same size (e.g., if you set the window extent, the viewport is adjusted to keep the units isotropic).

MM_LOENGLISH	Each logical unit is mapped to 0.01 inch. Positive x is to the right; positive y is at the top.

MM_LOMETRIC	Each logical unit is mapped to 0.1 millimeter. Positive x is to the right; positive y is at the top.

MM_TEXT	Each logical unit is mapped to one device pixel. Positive x is to the right; positive y is at the bottom.

MM_TWIPS	Each logical unit is mapped to one twentieth of a printer's point (1/1440 inch). Positive x is to the right; positive y is at the top.


See Also

TDC::SetMapMode


TDC::GetNearestColor

See Also	TDC

Syntax

TColor GetNearestColor(TColor Color) const;

Description

Returns the color nearest to the given Color argument for the current palette of this DC.


See Also

TColor


TDC::GetOutlineTextMetrics

See Also	TDC

Form 1

uint32 GetOutlineTextMetrics(uint data, OUTLINETEXTMETRIC far& otm);

Form 2

uint16 GetOutlineTextMetrics(uint data, OUTLINETEXTMETRIC far& otm);

Description

Retrieves metric information for TrueType fonts on this DC and copies it to the given array of OUTLINETEXTMETRIC structures, otm. This structure contains a TEXTMETRIC and several other metric members, as well as four string-pointer members for holding family, face, style, and full font names. Since memory must be allocated for these variable-length strings in addition to the font metric data, you must pass (with the data argument) the total number of bytes required for the retrieved data. If GetOutlineTextMetrics is called with otm = 0, the function returns the total buffer size required. You can then assign this value to data in subsequent calls.

Returns nonzero if the call is successful; otherwise, returns 0.


See Also

TDC::GetTextMetrics

OUTLINETEXTMETRIC struct

TEXTMETRIC struct


TDC::GetPixel

See Also	TDC

Form 1

TColor GetPixel(int x, int y) const;

Form 2

TColor GetPixel(const TPoint& point) const;

Description

Returns the color of the pixel at the given location.


See Also

TDC::SetPixel

TPoint


TDC::GetPolyFillMode

See Also	TDC

Syntax

int GetPolyFillMode() const;

Description

Returns the current polygon-filling mode for this DC, either ALTERNATE or WINDING.


See Also

TDC::SetPolyFillMode


TDC::GetROP2()

See Also	TDC

Syntax

int GetROP2() const;

Description

Returns the current drawing (raster operation) mode of this DC.


See Also

TDC::SetROP2


TDC::GetStretchBltMode

See Also	TDC

Syntax

int GetStretchBltMode() const;

Description

Returns the current stretching mode for this DC: BLACKONWHITE, COLORONCOLOR, or WHITEONBLACK. The stretching mode determines how bitmaps are stretched or compressed by the StretchBlt function.


See Also

TDC::SetStretchBltMode

TDC::StretchBlt


TDC::GetSystemPaletteEntries

See Also	TDC

Syntax

uint GetSystemPaletteEntries(int start, int num, PALETTEENTRY far* entries) const;

Description

Retrieves a range of up to num palette entries, starting at start, from the system palette to the entries array of PALETTEENTRY structures. Returns the actual number of entries transferred.


See Also

PALETTEENTRY struct


TDC::GetSystemPaletteUse

See Also	TDC

Syntax

uint GetSystemPaletteUse() const;

Description

Determines whether this DC has access to the full system palette. Returns SYSPAL_NOSTATIC or SYSPAL_STATIC.


See Also

TDC::SetSystemPaletteUse


TDC::GetTabbedTextExtent

See Also	TDC

Form 1

bool GetTabbedTextExtent(const char far* string, int stringLen, int numPositions, const int far* positions, TSize& size) const;

Form 2

TSize GetTabbedTextExtent(const char far* string, int stringLen, int numPositions, const int far* positions) const;

Description

Computes the extent (width and height) in logical units of the text line consisting of stringLen characters from the null-terminated string. The extent is calculated from the metrics of the current font or this DC, but ignores the current clipping region. In the first version of GetTabbedTextExtent, the extent is returned in size; in the second version, the extent is the returned TSize object. Width is size.x and width is size.y.

The width calculation includes the spaces implied by any tab codes in the string. Such tab codes are interpreted using the numPositions and positions arguments. The positions array specifies numPositions tab stops given in device units. The tab stops must have strictly increasing values in the array. If numPositions and positions are both 0, tabs are expanded to eight times the average character width. If numPositions is 1, all tab stops are taken to be positions[0] apart.

If kerning is being applied, the sum of the extents of the characters in a string might not equal the extent of the string.


See Also

TDC::TabbedTextOut

TDC::GetTextExtent

TSize


TDC::GetTextAlign

See Also	TDC

Syntax

uint GetTextAlign() const;

Description

If successful, returns the current text-alignment flags for this DC; otherwise, returns the value GDI_ERROR. The text-alignment flags determine how TDC::TextOut and TDC::ExtTextOut align text strings in relation to the first character's screen position. GetTextAlign returns certain combinations of the flags listed in the following table:

Value	Meaning

TA_BASELINE	The reference point will be on the baseline of the text.

TA_BOTTOM	The reference point will be on the bottom edge of the bounding rectangle.

TA_TOP	The reference point will be on the top edge of the bounding rectangle.

TA_CENTER	The reference point will be aligned horizontally with the center of the bounding rectangle.

TA_LEFT	The reference point will be on the left edge of the bounding rectangle.

TA_RIGHT	The reference point will be on the right edge of the bounding rectangle.

TA_NOUPDATECP	The current position is not updated after each text output call.

TA_UPDATECP	The current position is updated after each text output call.

When the current font has a vertical default baseline (as with Kanji) the following values replace TA_BASELINE and TA_CENTER:

VTA_BASELINE	The reference point will be on the baseline of the text.

VTA_CENTER	The reference point will be aligned vertically with the center of the bounding rectangle.

The text-alignment flags are not necessarily single bit-flags and might be equal to 0. The flags must be examined in groups of the following related flags:

TA_LEFT, TA_RIGHT, and TA_CENTER

TA_BOTTOM, TA_TOP, and TA_BASELINE

TA_NOUPDATECP and TA_UPDATECP

If the current font has a vertical default baseline (as with Kanji), these are groups of related flags:

TA_LEFT, TA_RIGHT, and VTA_BASELINE

TA_BOTTOM, TA_TOP, and VTA_CENTER

TA_NOUPDATECP and TA_UPDATECP

To verify that a particular flag is set in the return value of this function, the application must perform the following steps:

1.	Apply the bitwise OR operator to the flag and its related flags.

2.	Apply the bitwise AND operator to the result and the return value.

3.	Test for the equality of this result and the flag.

The following example shows a method for determining which horizontal alignment flag is set:

switch ((TA_LEFT | TA_RIGHT | TA_CENTER) & dc.GetTextAlign()) {

case TA_LEFT:

...

case TA_RIGHT:

...

case TA_CENTER:

...

}


See Also

TDC::SetTextAlign

TDC::TextOut

TDC::ExtTextOut


TDC::GetTextCharacterExtra

See Also	TDC

Syntax

int GetTextCharacterExtra() const;

Description

If successful, returns the current intercharacter spacing, in logical units, for this DC; otherwise, returns INVALID_WIDTH.


See Also

TDC::SetTextCharacterExtra


TDC::GetTextColor

See Also	TDC

Syntax

TColor GetTextColor() const;

Description

Returns the current text color of this DC. The text color determines the color displayed by TDC::TextOut and TDC::ExtTextOut.


See Also

TDC::SetTextColor

TDC::TextOut

TDC::ExtTextOut

TColor


TDC::GetTextExtent

See Also	TDC

Form 1

bool GetTextExtent(const char far* string, int stringLen, TSize& size);

Form 2

TSize GetTextExtent(const char far* string, int stringLen);

Description

Computes the extent (width and height) in logical units of the text line consisting of stringLen characters from the null-terminated string. The extent is calculated from the metrics of the current font or this DC, but ignores the current clipping region. In the first version of GetTextExtent the extent is returned in size; in the second version, the extent is the returned TSize object. Width is size.cx and height is size.cy.

If kerning is being applied, the sum of the extents of the characters in a string might not equal the extent of the string.


See Also

TSize


TDC::GetTextFace

See Also	TDC

Syntax

int GetTextFace(int count, char far* facename) const;

Description

Retrieves the typeface name for the current font on this DC. Up to count characters of this name are copied to facename. If successful, GetTextFace returns the number of characters actually copied; otherwise, it returns 0.


See Also

TDC::GetTextAlign

TDC::GetTextMetrics


TDC::GetTextMetrics

See Also	TDC

Syntax

bool GetTextMetrics(TEXTMETRIC far& metrics) const;

Description

Fills the metrics structure with metrics data for the current font on this DC. Returns true if the call is successful; otherwise, returns false.


See Also

TEXTMETRIC struct


TDC::GetViewportExt

See Also	TDC

Form 1

bool GetViewportExt(TSize& extent) const;

Form 2

TSize GetViewportExt() const;

Description

The first version retrieves this DC's current viewport's x- and y-extents (in device units) and places the values in extent. This version returns true if the call is successful; otherwise, it returns false. The second version returns only these x- and y-extents.

The extent value determines the amount of stretching or compression needed in the logical coordinate system to fit the device coordinate system. extent also determines the relative orientation of the two coordinate systems.


See Also

TDC::SetViewportExt

TSize


TDC::GetViewportOrg

See Also	TDC

Form 1

bool GetViewportOrg(TPoint& point) const;

Form 2

TPoint GetViewportOrg() const;

Description

The first version sets in the point argument the x- and y-extents (in device-units) of this DC's viewport. It returns true if the call is successful; otherwise, it returns false. The second version returns the x- and y-extents (in device-units) of this DC's viewport.


See Also

TDC::SetViewportOrg

TDC::OffsetViewportOrg

TPoint


TDC::GetWindowExt

See Also	TDC

Form 1

bool GetWindowExt(TSize& extent) const;

Form 2

TSize GetWindowExt() const;

Description

Retrieves this DC's window current x- and y-extents (in device units). The first version places the values in extent and returns true if the call is successful; otherwise, it returns false. The second version returns the current extent values. The extent value determines the amount of stretching or compression needed in the logical coordinate system to fit the device coordinate system. extent also determines the relative orientation of the two coordinate systems.


See Also

TDC::SetWindowExt

TSize


TDC::GetWindowOrg

See Also	TDC

Form 1

bool GetWindowOrg(TPoint& point) const;

Form 2

TPoint GetWindowOrg() const;

Description

Places in point the x- and y-coordinates of the origin of the window associated with this DC. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::SetWindowOrg

TDC::OffsetWindowOrg

TPoint


TDC::GrayString

See Also	TDC

Syntax

virtual bool GrayString(const TBrush& brush, GRAYSTRINGPROC outputFunc, const char far* string, int count, const TRect& r);

Description

Draws in the given rectangle (r) up to count characters of gray text from string using the given brush, brush, and the current font for this DC. If count is -1 and string is null-terminated, the whole string is written. The rectangle must be specified in logical units. If brush is 0, the text is grayed with the same brush used to draw window text on this DC. Gray text is primarily used to indicate disabled commands and menu items.

GrayString writes the selected text to a memory bitmap, grays the bitmap, then displays the result. The graying is performed regardless of the current brush and background color.

The outputFunc pointer to a function can specify the procedure instance of an application-supplied drawing function and is defined as

typedef BOOL (CALLBACK* GRAYSTRINGPROC)(HDC, LPARAM, int);

If outputFunc is 0, GrayString uses TextOut and string is assumed to be a normal, null-terminated character string. If string cannot be handled by TextOut (for example, the string is stored as a bitmap), you must provide a suitable drawing function via outputFunc.

If the device supports a solid gray color, it is possible to draw gray strings directly without using GraySring. Call GetSysColor to find the color value; for example, G of COLOR_GRAYTEXT. If G is nonzero (non-black), you can set the text color with SetTextColor(G) and then use any convenient text-drawing function.

GrayString returns true if the call is successful; otherwise, it returns false. Failure can result if TextOut or outputFunc return false, or if there is insufficient memory to create the bitmap.


See Also

TDC::TextOut

TBrush

TRect


TDC::operator HDC()

TDC

Syntax

operator HDC() const{return Handle;}

Description

Typecasting operator. Converts a pointer to type HDC (the data type representing the handle to a DC).


TDC::IntersectClipRect

See Also	TDC

Syntax

int IntersectClipRect(const TRect& rect);

Description

Creates a new clipping region for this DC's window by forming the intersection of the current region with the rectangle specified by rect. The return value indicates the resulting clipping region's type as follows:

Region	Meaning

COMPLEXREGION	Clipping Region has overlapping borders.

ERROR	Invalid DC.

NULLREGION	Clipping region is empty.

SIMPLEREGION	Clipping region has no overlapping borders.


See Also

TDC::GetClipBox

TRect


TDC::InvertRect

See Also	TDC

Form 1

bool InvertRect(int x1, int x2, int y1, int y2);

Form 2

bool InvertRect(const TRect& rect);

Description

Inverts the given rectangle, rect, on this DC. On monochrome displays, black and white pixels are interchanged. On color displays, inversion depends on how the colors are generated for particular displays. Calling InvertRect an even number of times restores the original colors. InvertRect returns true if the call is successful; otherwise, it returns false.


See Also

TRect


TDC::InvertRgn

See Also	TDC

Syntax

bool InvertRgn(const TRegion& region);

Description

Inverts the given region, on this DC. On monochrome displays, black and white pixels are interchanged. On color displays, inversion depends on how the colors are generated for particular displays. Calling InvertRegion an even number (n>=2 ) of times restores the original colors. Returns true if the call is successful; otherwise, it returns false.


See Also

TDC::PaintRgn

TDC::FillRgn

TRegion


TDC::LineTo

See Also	TDC

Form 1

bool LineTo(int x, int y);

Form 2

bool LineTo(const TPoint& point);

Description

Draws a line on this DC using the current pen object. The line is drawn from the current position up to, but not including, the given end point, which is specified by (x, y) or by point. If the call is successful, LineTo returns true and the current point is reset to point; otherwise, it returns false.


See Also

TPoint


TDC::LPtoDP

See Also	TDC

Syntax

bool LPtoDP(TPoint* points, int count = 1) const;

Description

Converts each of the count points in the points array from logical points to device points. The conversion depends on this DC's current mapping mode and the settings of its window and viewport origins and extents. Returns true if the call is successful; otherwise, it returns false.


See Also

TDC::DPtoLP

TPoint


TDC::MaskBlt

See Also	TDC

Syntax

bool MaskBlt(const TRect& dst, const TDC& srcDC, const TPoint& src, const TBitmap& maskBm, const TPoint& maskPos, uint32 rop=SRCCOPY);

Description

 Copies a bitmap from the given source DC to this DC. MaskBlt combines the color data from source and destination bitmaps using the given mask and raster operation. The srcDC argument specifies the DC from which the source bitmap will be copied. The destination bitmap is given by the rectangle, dst. The source bitmap has the same width and height as dst. The src argument specifies the logical coordinates of the upper left corner of the source bitmap. The maskBm argument specifies a monochrome mask bitmap. An error will occur if maskBm is not monochrome. The maskPos argument gives the upper left corner coordinates of the mask. The raster-operation code, rop, specifies how the source, mask, and destination bitmaps combine to produce the new destination bitmap. The raster-operation codes are as follows:

Value of rop	Meaning

BLACKNESS	Fill dst with index-0 color of physical palette (default is black).

DSTINVERT	Invert dst.

MERGECOPY	Merge the colors of source with mask with Boolean AND.

MERGEPAINT	Merge the colors of inverted-source with the colors of dst using Boolean OR.

NOTSRCCOPY	Copy inverted-source to dst.

NOTSRCERASE	Combine the colors of source and dst using Boolean OR, then invert result.

PATCOPY	Copy mask to dst.

PATINVERT	Combine the colors of mask with the colors of dst using Boolean XOR.

PATPAINT	Combine the colors of mask with the colors of inverted-source using Boolean OR, then combine the result with the colors of dst using Boolean OR.

SRCAND	Combine the colors of source and dst using the Boolean AND.

SRCCOPY	Copy source directly to dst.

SRCERASE	Combine the inverted colors of dst with the colors of source using Boolean AND.

SRCPAINT	Combine the colors of source and dst using Boolean OR.

WHITENESS	Fill dst with index-1 color of physical palette (default is white).

If rop indicates an operation that excludes the source bitmap, the srcDC argument must be 0. A value of 1 in the mask indicates that the destination and source pixel colors should be combined using the high-order word of rop. A value of 0 in the mask indicates that the destination and source pixel colors should be combined using the low-order word of rop. If the mask rectangle is smaller than dst, the mask pattern will be suitably duplicated.

When recording an enhanced metafile, an error occurs if the source DC identifies the enhanced metafile DC.

If a rotation or shear transformation is in effect for the source DC when MaskBlt is called, an error occurs. Other transformations are allowed. If necessary, MaskBlt will adjust the destination and mask color formats to match that of the source bitmaps. Before using MaskBlt, an application should call GetDeviceCaps to determine if the source and destination DCs support MaskBlt.

MaskBlt returns true if the call is successful; otherwise, it returns false.


See Also

TDC::BitBlt

TDC::PlgBlt

TDC::GetDeviceCaps

TBitmap

TPoint

TRect


TDC::ModifyWorldTransform

See Also	TDC

Syntax

bool ModifyWorldTransform(XFORM far& xform, uint32 mode);

Description

 Changes the current world transformation for this DC using the given xform and mode arguments. mode determines how the given XFORM structure is applied, as listed below.

Value	Meaning

MWT_IDENTITY	Resets the current world transformation using the identity matrix. If this mode is specified, the XFORM structure pointed to by lpXform is ignored.

MWT_LEFTMULTIPLY	Multiplies the current transformation by the data in the XFORM structure. (The data in the XFORM structure becomes the left multiplicand, and the data for the current transformation becomes the right multiplicand.)

MWT_RIGHTMULTIPLY	Multiplies the current transformation by the data in the XFORM structure. (The data in the XFORM structure becomes the right multiplicand, and the data for the current transformation becomes the left multiplicand.) ModifyWorldTransform returns true if the call is successful; otherwise, it returns false.


See Also

TDC::SetWorldTransform

XFORM struct


TDC::MoveTo

See Also	TDC

Form 1

bool MoveTo(int x, int y);

Form 2

bool MoveTo(const TPoint& point);

Form 3

bool MoveTo(const TPoint& point, TPoint& oldPoint);

Description

Moves the current position of this DC to the given x- and y-coordinates or to the given point. The third version sets the previous current position in oldPoint. Returns true if the call is successful; otherwise, returns false.


See Also

TPoint


TDC::OffsetClipRgn

See Also	TDC

Syntax

int OffsetClipRgn(const TPoint& delta);

Description

Moves the clipping region of this DC by the x- and y-offsets specified in delta. The return value indicates the resulting clipping region's type as follows:

Region	Meaning

COMPLEXREGION	Clipping region has overlapping borders.

ERROR	Invalid DC.

NULLREGION	Clipping region is empty.

SIMPLEREGION	Clipping region has no overlapping borders.


See Also

TDC::GetClipBox

TPoint


TDC::OffsetViewportOrg

See Also	TDC

Syntax

virtual bool OffsetViewportOrg(const TPoint& delta, TPoint* oldOrg = 0);

Description

Modifies this DC's viewport origin relative to the current values. The delta x- and y-components are added to the previous origin and the resulting point becomes the new viewport origin. The previous origin is saved in oldOrg. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::SetViewportOrg

TDC::GetViewportOrg

TPoint


TDC::OffsetWindowOrg

See Also	TDC

Syntax

bool OffsetWindowOrg(const TPoint& delta, TPoint* oldOrg = 0);

Description

Modifies this DC's window origin relative to the current values. The delta x- and y-components are added to the previous origin and the resulting point becomes the new window origin. The previous origin is saved in oldOrg. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::GetWindowOrg

TDC::SetWindowOrg

TPoint


TDC::OWLFastWindowFrame

See Also	TDC

Syntax

void OWLFastWindowFrame(TBrush& brush, TRect& rect, int xWidth, int yWidth)

Description

Draws a frame of the specified size and thickness with the given brush. The old brush is restored after completion.


See Also

TBrush

TRect


TDC::PaintRgn

See Also	TDC

Syntax

bool PaintRgn(const TRegion& region);

Description

Paints (fills) the given region on this DC using the currently selected brush. Returns true if the call is successful; otherwise, returns, false.


See Also

TDC::FillRgn

TDC::SelectObject

TRegion


TDC::PatBlt

See Also	TDC

Form 1

bool PatBlt(int x, int y, int w, int h, uint32 rop=PATCOPY);

Form 2

bool PatBlt(const TRect& dst, uint32 rop=PATCOPY);

Description

Paints the given rectangle using the currently selected brush for this DC. The rectangle can be specified by its upper left coordinates (x, y), width w, and height h, or by a single TRect argument. The raster-operation code, rop, determines how the brush and surface color(s) are combined, as explained in the following table:

Value	Meaning

PATCOPY	Copies pattern to destination bitmap.

PATINVERT	Combines destination bitmap with pattern using the Boolean OR operator.

DSTINVERT	Inverts the destination bitmap.

BLACKNESS	Turns all output to binary 0s.

WHITENESS	Turns all output to binary 1s.

The allowed values of rop for this function are a limited subset of the full 256 ternary raster-operation codes; in particular, an operation code that refers to a source cannot be used with PatBlt.

Not all devices support the PatBlt function, so applications should call TDC::GetDeviceCaps to check the features supported by this DC.

PatBlt returns true if the call is successful; otherwise, returns false.


See Also

TDC::GetDeviceCaps

TRect


TDC::PathToRegion

TDC

Syntax

HRGN PathToRegion();

Description

If successful, returns a region created from the closed path in this DC; otherwise, returns 0.


TDC::Pie

See Also	TDC

Form 1

bool Pie(int x1, int y1, int x2, int y2, int x3, int y3, int x4, int y4);

Form 2

bool Pie(const TRect& rect, const TPoint& start, const TPoint& end);

Description

Using the currently selected pen and brush objects, draws and fills a pie-shaped wedge by drawing an elliptical arc whose center and end points are joined by lines. The center of the ellipse is the center of the rectangle specified either by (x1, y1)/(x2, y2) or by the rect argument. The starting/ending points of pie are specified either by (x3, y3)/(x4, y4) or by the points Start and End. Returns true if the call is successful; otherwise, returns false. The current position is neither used nor altered by this call.


See Also

TDC::Chord

TDC::Arc

TPoint

TRegion

TRect


TDC::PlayMetaFile

See Also	TDC

Syntax

bool PlayMetaFile(const TMetaFilePict& metaFile);

Description

Plays the contents of the given metaFile on this DC. The metafile can be played any number of times. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::EnumMetaFile

TDC::PlayMetaFileRecord

TMetaFilePict


TDC::PlayMetaFileRecord

See Also	TDC

Syntax

void PlayMetaFileRecord(HANDLETABLE far& Handletable, METARECORD far& metaRecord, int count);

Description

Plays the metafile record given in metaRecord to this DC by executing the GDI function call contained in that record. Handletable specifies the object handle table to be used. count specifies the number of handles in the table.


See Also

TDC::PlayMetaFile

TDC::EnumMetaFile

HANDLETABLE struct

METARECORD struct


TDC::PlgBlt

See Also	TDC

Syntax

bool PlgBlt(const TPoint& dst, const TDC& srcDC, const TRect& src, const TBitmap& maskBm, const TPoint& maskPos, uint32 rop=SRCCOPY);

Description

32-bit only. Performs a bit-block transfer from the given source DC to this DC. Color bits are copied from the src rectangle on srcDC, the source DC, to the parallelogram dst on this DC. The dst array specifies three points A,B, and C as the corners of the destination parallelogram. The fourth point D is generated internally from the vector equation D = B + C - A. The upper left corner of src is mapped to A, the upper right corner to B, the lower left corner to C, and the lower right corner to D. An optional monochrome bitmap can be specified by the maskBm argument. (If maskBm specifies a valid monochrome bitmap, PlgBlt uses it to mask the colorbits in the source rectangle. An error occurs if maskBm is not a monochrome bitmap.) maskPos specifies the upper left corner coordinates of the mask bitmap. With a valid maskBm, a value of 1 in the mask causes the source color pixel to be copied to dst; a value of 0 in the mask indicates that the corresponding color pixel in dst will not be changed. If the mask rectangle is smaller than dst, the mask pattern will be suitably duplicated.

The destination coordinates are transformed according to this DC (the destination DC). The source coordinates are transformed according to the source DC. If a rotation or shear transformation is in effect for the source DC when PlgBlt is called, an error occurs. Other transformations, such as scaling, translation, and reflection are allowed. The stretching mode of this DC (the destination DC) determines how PlgBlt will stretch or compress the pixels if necessary. When recording an enhanced metafile, an error occurs if the source DC identifies the enhanced metafile DC.

If necessary, PlgBlt adjusts the source color formats to match that of the destination. An error occurs if the source and destination DCs are incompatible. Before using PlgBlt, an application should call  GetDeviceCaps to determine if the source and destination DCs are compatible.

PlgBlt returns true if the call is successful; otherwise, it returns false.


See Also

TDC::GetDeviceCaps

TDC::MaskBlt

TDC::SetStretchBltMode

TDC::StretchBlt

TBitmap

TPoint

TRect


TDC::PolyBezier

See Also	TDC

Syntax

bool PolyBezier(const TPoint* points, int count);

Description

Draws one or more connected cubic Bezier splines through the points specified in the points array using the currently selected pen object. The first spline is drawn from the first to the fourth point of the array using the second and third points as controls. Subsequent splines, if any, each require three additional points in the array, since the previous end point is taken as the next spline's start point. The count argument ( >= 4 ) specifies the total number of points needed to specify the complete drawing. To draw n splines, count must be set to (3n + 1). Returns true if the call is successful; otherwise, returns false. The current position is neither used nor altered by this call. The resulting figure is not filled.


See Also

TDC::PolyBezierTo

TPoint


TDC::PolyBezierTo

See Also	TDC

Syntax

bool PolyBezierTo(const TPoint* points, int count);

Description

Draws one or more connected cubic Beziers plines through the points specified in the points array using the currently selected pen object. The first spline is drawn from the current position to the third point of the array using the first and second points as controls. Subsequent splines, if any, each require three additional points in the array, since the previous end point is taken as the next spline's start point. The count argument ( >= 4 ) specifies the total number of points needed to specify the complete drawing. To draw n splines, count must be set to 3n. Returns true if the call is successful; otherwise, returns false. The current position is moved to the end point of the final Bezier curve. The resulting figure is not filled.


See Also

TDC::PolyBezier

TPoint


TDC::PolyDraw

See Also	TDC

Syntax

bool PolyDraw(const TPoint* points, uint8* types, int count);

Description

Using the currently selected pen object, draws one or more possibly disjoint sets of line segments or Bezier splines or both on this DC. The count points in the points array provide the end points for each line segment or the end points and control points for each Bezier spline or both. The count BYTEs in the types array determine as follows how the corresponding point in points is to be interpreted:

Byte	Meaning

PT_BEZIERTO	This point is a control or end point for a Bezier spline. PT_BEZIERTO types must appear in sets of three: the current position is the Bezier start point; the first two PT_BEZIERTO points are the Bezier control points; and the third PT_BEZIERTO point is the Bezier end point, which becomes the new current point. An error occurs if the PT_BEZIERTO types do not appear in sets of three. An end-point PT_BEZIERTO can be bit-wise OR'd with PT_CLOSEFIGURE to indicate that the current figure is to be closed by drawing a spline from this end point to the start point of the most recent disjoint figure.

PT_CLOSEFIGURE	Optional flag that can be bit-wise OR'd with PT_LINETO or PT_BEZIERTO, as explained above. Closure updates the current point to the new end point.

PT_LINETO	A line is drawn from the current position to this point, which then becomes the new current point. PT_LINETO can be bit-wise OR'd with PT_CLOSEFIGURE to indicate that the current figure is to be closed by drawing a line segment from this point to the start point of the most recent disjoint figure.

PT_MOVETO	This point starts a new (disjoint) figure and becomes the new current point.

PolyDraw is an alternative to consecutive calls to MoveTo, LineTo, Polyline, PolyBezier, and PolyBezierTo. If there is an active path invoked via BeginPath, PolyDraw will add to this path.

Returns true if the call is successful; otherwise, returns false.


See Also

TDC::MoveTo

TDC::LineTo

TDC::PolyBezier

TDC::PolyBezierTo

TDC::Polyline

TDC::BeginPath

TPoint


TDC::Polygon

See Also	TDC

Syntax

bool Polygon(const TPoint* points, int count);

Description

 Using the current pen and polygon-filling mode, draws and fills on this DC a closed polygon with a number of line segments equal to count (which must be >= 2). The points array specifies the vertices of the polygon to be drawn. The polygon is automatically closed, if necessary, by drawing a line from the last to the first vertex. The current position is neither used nor altered by Polygon. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::Polyline

TDC::SetPolyFillMode

TDC::GetPolyFillMode

TPoint


TDC::Polyline

See Also	TDC

Syntax

bool Polyline(const TPoint* points, int count);

Description

Using the current pen object, draws on this DC a count of line segments (there must be at least 2). The points array specifies the sequence of points to be connected. The current position is neither used nor altered by Polyline. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::Polygon

TDC::PolyPolyline

TPoint


TDC::PolylineTo

See Also	TDC

Syntax

bool PolylineTo(const TPoint* points, int count);

Description

Draws one or more connected line segments on this DC using the currently selected pen object. The first line is drawn from the current position to the first of the count points in the points array. Subsequent lines, if any, connect the remaining points in the array, with each end point providing the start point of the next segment. The final end point becomes the new current point. No filling occurs even if a closed figure is drawn. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::PolyDraw

TDC::LineTo

TPoint


TDC::PolyPolygon

See Also	TDC

Syntax

bool PolyPolygon(const TPoint* points, const int* PolyCounts, int count);

Description

Using the current pen and polygon-filling mode, draws and fills on this DC the number of closed polygons indicated in count (which must be >= 2). The polygons can overlap. The points array specifies the vertices of the polygons to be drawn. PolyCounts is an array of count integers specifying the number of vertices in each polygon. Each polygon must be a closed polygon. The current position is neither used nor altered by Polygon. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::PolyPolyline

TDC::SetPolyFillMode

TDC::GetPolyFillMode

TPoint


TDC::PolyPolyline

See Also	TDC

Syntax

bool PolyPolyline(const TPoint* points, const int* PolyCounts, int count);

Description

Using the currently selected pen object, draws on this DC the number of polylines (connected line segments) indicated in count. The resulting figures are not filled. The PolyCounts array provides count integers specifying the number of points (>= 2) in each polyline. The points array provides, consecutively, each of the points to be connected. Returns true if the call is successful; otherwise, returns false. The current position is neither used nor altered by this call.


See Also

TDC::Polyline

TDC::PolyPolygon

TPoint


TDC::PtVisible

See Also	TDC

Syntax

bool PtVisible(const TPoint& point) const;

Description

Returns true if the given point lies within the clipping region of this DC; otherwise, returns false.


See Also

TDC::RectVisible

TPoint


TDC::RealizePalette

See Also	TDC

Syntax

int RealizePalette();

Description

Maps to the system palette the logical palette entries selected into this DC. Returns the number of entries in the logical palette that were mapped to the system palette.


See Also

TPalette


TDC::Rectangle

See Also	TDC

Form 1

bool Rectangle(int x1, int y1, int x2, int y2);

Form 2

bool Rectangle(const TPoint& p1, const TPoint& p2);

Form 3

bool Rectangle(const TPoint& point, const TSize& s);

Form 4

bool Rectangle(const TRect& rect);

Description

Draws and fills a rectangle of the given size on this DC with the current pen and brush objects. The current position is neither used nor altered by this call. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::RoundRect

TPoint

TRect

TSize


TDC::RectVisible

See Also	TDC

Syntax

bool RectVisible(const TRect& rect) const;

Description

Returns true if any part of the given rectangle, rect, lies within the clipping region of this DC; otherwise, returns false.


See Also

TDC::PtVisible

TRect


TDC::ResetDC

See Also	TDC

Syntax

virtual bool ResetDC(DEVMODE far& devMode);

Description

Updates this DC using data in the given devMode structure. Returns true if the call is successful; otherwise, returns false.


See Also

DEVMODE struct


TDC::RestoreBrush

See Also	TDC

Syntax

void RestoreBrush();

Description

Restores the original GDI brush object to this DC.


See Also

TDC::OrgBrush

TBrush


TDC::RestoreDC

See Also	TDC

Syntax

virtual bool RestoreDC(int savedDC = -1);

Description

Restores the given savedDC. Returns true if the context is successfully restored; otherwise, returns false.


See Also

TDC::SaveDC


TDC::RestoreFont

See Also	TDC

Syntax

virtual void RestoreFont();

Description

Restores the original GDI font object to this DC.


See Also

TDC::OrgFont

TFont


TDC::RestoreObjects

See Also	TDC

Syntax

void RestoreObjects();

Description

Restores all the original GDI objects to this DC.


See Also

TGdiObject


TDC::RestorePalette

See Also	TDC

Syntax

void RestorePalette();

Description

Restores the original GDI palette object to this DC.


See Also

TDC::OrgPalette

TPalette


TDC::RestorePen

See Also	TDC

Syntax

void RestorePen();

Description

Restores the original GDI pen object to this DC.


See Also

TDC::OrgPen

TPen


TDC::RestoreTextBrush

See Also	TDC

Syntax

void RestoreTextBrush();

Description

Restores the original GDI text brush object to this DC.


See Also

TBrush


TDC::RoundRect

See Also	TDC

Form 1

bool RoundRect(int x1, int y1, int x2, int y2, int x3, int y3);

Form 2

bool RoundRect(const TPoint& p1, const TPoint& p2, const TPoint& rad);

Form 3

bool RoundRect(const TPoint& p, const TSize& s, const TPoint& rad);

Form 4

bool RoundRect(const TRect& rect, const TPoint& rad);

Description

Draws and fills a rounded rectangle of the given size on this DC with the current pen and brush objects. The current position is neither used nor altered by this call. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::Rectangle

TPoint

TRect

TSize


TDC::SaveDC

See Also	TDC

Syntax

virtual int SaveDC() const;

Description

Saves the current state of this DC on a context stack. The saved state can be restored later with RestoreDC. Returns a value specifying the saved DC or 0 if the call fails.


See Also

TDC::RestoreDC


TDC::ScaleViewportExt

See Also	TDC

Syntax

virtual bool ScaleViewportExt(int xNum, int xDenom, int yNum, int yDenom, TSize* oldExtent = 0);

Description

Modifies this DC's viewport extents relative to the current values. The new extents are derived as follows:

xNewVE = (xOldVE * xNum)/ xDenom

yNewVE = (I * yNum)/ yDenom

The previous extents are saved in oldExtent. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::SetViewportExt

TSize


TDC::ScaleWindowExt

See Also	TDC

Syntax

virtual bool ScaleWindowExt(int xNum, int xDenom, int yNum, int yDenom, TSize* oldExtent = 0);

Description

Modifies this DC's window extents relative to the current values. The new extents are derived as follows:

xNewWE = (xOldWE * xNum)/ xDenom

yNewWE = (yOldWE * yNum)/ yDenom

The previous extents are saved in oldExtent. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::SetWindowExt

TSize


TDC::ScrollDC

See Also	TDC

Form 1

bool ScrollDC(int x, int y, const TRect& scroll, const TRect& clip, TRegion& updateRgn, TRect& updateRect);

Form 2

bool ScrollDC(const TPoint& delta, const TRect& scroll, const TRect& clip, TRegion& updateRgn, TRect& updateRect);

Description

Scrolls a rectangle of bits horizontally by x (or delta.x in the second version) device-units, and vertically by y (or delta.y) device-units on this DC. The scrolling and clipping rectangles are specified by scroll and clip. ScrollDC provides data in the updateRgn argument telling you the region (not necessarily rectangular) that was uncovered by the scroll. Similarly, ScrollDC reports in updateRect the rectangle (in client coordinates) that bounds the scrolling update region. This is the largest area that requires repainting.

Returns true if the call is successful; otherwise, returns false.


See Also

TPoint

TRect

TRegion


TDC::SelectClipPath

TDC

Syntax

bool SelectClipPath(int mode);

Description

Selects the current path on this DC as a clipping region, combining any existing clipping region using the specified mode as shown in the following table:

Mode	Meaning

RGN_AND	The new clipping region includes the overlapping areas of the current clipping region and the current path (intersection).

RGN_COPY	The new clipping region is the current path.

RGN_DIFF	The new clipping region includes the areas of the current clipping region with those of the current path excluded.

RGN_OR	The new clipping region includes the combined areas of the current clipping region and the current path (union).

RGN_XOR	The new clipping region includes the combined areas of the current clipping region and the current path but without the overlapping areas.

Returns true if the call is successful; otherwise, returns false.


TDC::SelectClipRgn

See Also	TDC

Syntax

int SelectClipRgn(const TRegion& region);

Description

Selects the given region as the current clipping region for this DC. A copy of the given region is used, letting you select the same region for other DC objects. The return value indicates the new clipping region's type as follows:

Region	Meaning

COMPLEXREGION	Clipping Region has overlapping borders.

ERROR	Invalid DC.

NULLREGION	Clipping region is empty.

SIMPLEREGION	Clipping region has no overlapping borders.


See Also

TDC::OffsetClipRgn

TDC::GetClipBox

TRegion


TDC::SelectObject

See Also	TDC

Form 1

void SelectObject(const TBrush& brush);

Form 2

void SelectObject(const TPen& pen);

Form 2

virtual void SelectObject(const TFont& font);

Form 4

void SelectObject(const TPalette& palette, bool forceBackground = false);

Description

Selects the given GDI object into this DC. The previously selected object is saved in the appropriate OrgXXX protected data member. For a palette argument, if forceBackgound is set false (the default), the selected logical palette is a foreground palette when the window has input focus. If forceBackground is true, the selected palette is always a background palette whether the window has focus or not.


See Also

TDC::OrgBrush

TDC::OrgFont

TDC::OrgPalette

TDC::OrgPen

TDC::OrgTextBrush

TBrush

TFont

TPalette

TPen

TMemoryDC::SelectObject


TDC::SelectStockObject

See Also	TDC

Syntax

virtual void SelectStockObject(int index);

Description

Selects into the DC a predefined stock pen, brush, font, or palette.


See Also

TPrintPreviewDC::SelectStockObject


TDC::SetBkColor

See Also	TDC

Syntax

virtual TColor SetBkColor(TColor color);

Description

Sets the current background color of this DC to the given color value or the nearest available. Returns 0x80000000 if the call fails.


See Also

TDC::GetBkColor

TColor


TDC::SetBkMode

See Also	TDC

Syntax

int SetBkMode(int mode);

Description

Sets the background mode to the given mode argument, which can be either OPAQUE or TRANSPARENT. Returns the previous background mode.


See Also

TDC::GetBkMode


TDC::SetBoundsRect

See Also	TDC

Syntax

uint SetBoundsRect(TRect& bounds, uint flags);

Description

Controls the accumulation of bounding rectangle information for this DC. Depending on the value of flags, the given bounds rectangle (possibly NULL) can combine with or replace the existing accumulated rectangle. flags can be any appropriate combination of the following values:

Constant	Meaning

DCB_ACCUMULATE	Add bounds (rectangular union) to the current accumulated rectangle.

DCB_DISABLE	Turn off bounds accumulation.

DCB_ENABLE	Turn on bounds accumulation (the default setting for bounds accumulation is disabled).

DCB_RESET	Set the bounding rectangle to empty.

DCB_SET	Set the bounding rectangle to bounds.

There are two bounding-rectangle accumulations, one for Windows and one for the application. The Windows-accumulated bounds can be queried by an application but not altered. The application can both query and alter the DC's accumulated bounds.


See Also

TDC::GetBoundsRect

TRect


TDC::SetBrushOrg

See Also	TDC

Syntax

bool SetBrushOrg(const TPoint& origin, TPoint* oldOrg = 0);

Description

Sets the origin of the currently selected brush of this DC with the given origin value. The previous origin is passed to oldOrg. Returns true if successful; otherwise, returns false.


See Also

TDC::GetBrushOrg

TPoint


TDC::SetDIBits

See Also	TDC

Form 1

bool SetDIBits(TBitmap& bitmap, uint16 startScan, uint16 numScans, const void HUGE* bits, const BITMAPINFO far& Info, uint16 usage);

Form 2

bool SetDIBits(TBitmap& Bitmap, const TDib& dib);

Description

The first version sets the pixels in bitmap (the given destination bitmap on this DC) from the source DIB (device-independent bitmap) color data found in the byte array bits and the BITMAPINFO structure, Info. numScan scanlines are taken from the DIB, starting at scanline startScan. The usage argument specifies how the bmiColors member of BITMAPINFO is interpreted, as explained in TDC::GetDIBits.

In the second version of SetDIBits, the pixels are set in bitmap from the given source TDib argument.

SetDIBits returns true if the call is successful; otherwise, it returns false.


See Also

TDC::GetDIBits

TDC::SetDIBitsToDevice

TBitmap

BITMAPINFO struct

TDib


TDC::SetDIBitsToDevice

See Also	TDC

Form 1

bool SetDIBitsToDevice(const TRect& dst, const TPoint& src, uint16 startScan, uint16 numScans, const void HUGE* bits, const BITMAPINFO far& bitsInfo, uint16 usage);

Form 2

bool SetDIBitsToDevice(const TRect& dst, const TPoint& src, const TDib& dib);

Description

The first version sets the pixels in dst (the given destination rectangle on this DC) from the source DIB (device-independent bitmap) color data found in the byte array bits and the BITMAPINFO structure, bitsInfo. The DIB origin is specified by the point src. numScan scanlines are taken from the DIB, starting at scanline startScan. The usage argument determines how the bmiColors member of BITMAPINFO is interpreted, as explained in TDC::GetDIBits.

In the second version of SetDIBitsToDevice, the pixels are set in dst from dib, the given source TDib argument.

SetDIBitsToDevice returns true if the call is successful; otherwise, it returns false.


See Also

TDC::GetDIBits

TDib

TPoint

TRect

BITMAPINFO struct


TDC::SetMapMode

See Also	TDC

Syntax

virtual int SetMapMode(int mode);

Description

Sets the current window mapping mode of this DC to mode. Returns the previous mapping mode value. The mapping mode defines how logical coordinates are mapped to device coordinates. It also controls the orientation of the device's x- and y-axes. See TDC::GetMapMode for a complete list of mapping modes.


See Also

TDC::GetMapMode


TDC::SetMapperFlags

TDC

Syntax

uint32 SetMapperFlags(uint32 flag);

Description

Alters the algorithm used by the font mapper when mapping logical fonts to physical fonts on this DC. If successful, the function sets the current font-mapping flag to flag and returns the previous mapping flag; otherwise GDI_ERROR is returned. The mapping flag determines whether the font mapper will attempt to match a font's aspect ratio to this DC's aspect ratio. If bit 0 of flag is set to 1, the mapper selects only matching fonts. If no matching fonts exist, a new aspect ratio is chosen and a font is retrieved to match this ratio.


TDC::SetMiterLimit

TDC

Syntax

bool SetMiterLimit(float newLimit, float* oldLimit = 0);

Description

Sets the limit of miter joins to newLimit and puts the previous value in oldLimit. Returns true if successful; otherwise, returns false.


TDC::SetPixel

See Also	TDC

Form 1

TColor SetPixel(int x, int y, TColor color);

Form 2

TColor SetPixel(const TPoint& p, TColor color);

Description

Sets the color of the pixel at the given location to the given color and returns the pixel's previous color.


See Also

TDC::GetPixel

TColor

TPoint


TDC::SetPolyFillMode

See Also	TDC

Syntax

int SetPolyFillMode(int mode);

Description

Sets the polygon-filling mode for this DC to the given mode value, either ALTERNATE or WINDING. Returns the previous fill mode.


See Also

TDC::GetPolyFillMode

TDC::Polygon


TDC::SetROP2

See Also	TDC

Syntax

int SetROP2(int mode);

Description

Sets the current foreground mix mode mode of this DC to the given mode value and returns the previous mode. The mode argument determines how the brush, pen, and existing screen image combine when filling and drawing. mode can be one of the following values:

Value	Meaning

R2_BLACK	Pixel is always binary 0.

R2_COPYPEN	Pixel is the pen color.

R2_MASKNOTPEN	Pixel is a combination of the colors common to both the display and the inverse of the pen.

R2_MASKPEN	Pixel is a combination of the colors common to both the pen and the display.

R2_MASKPENNOT	Pixel is a combination of the colors common to both the pen and the inverse of the display.

R2_MERGEPEN	Pixel is a combination of the pen color and the display color.

R2_MERGENOTPEN	Pixel is a combination of the display color and the inverse of the pen color.

R2_MERGEPENNOT	Pixel is a combination of the pen color and the inverse of the display color.

R2_NOP	Pixel remains unchanged.

R2_NOT	Pixel is the inverse of the display color.

R2_NOTCOPYPEN	Pixel is the inverse of the pen color.

R2_NOTMASKPEN	Pixel is the inverse of the R2_MASKPEN color.

R2_NOTMERGEPEN	Pixel is the inverse of the R2_MERGEPEN color.

R2_NOTXORPEN	Pixel is the inverse of the R2_XORPEN color.

R2_WHITE	Pixel is always binary 1.

R2_XORPEN	Pixel is a combination of the colors in the pen and in the display, but not in both.


See Also

TDC::GetROP2

TDC::GetDeviceCaps


TDC::SetStretchBltMode

See Also	TDC

Syntax

int SetStretchBltMode(int mode);

Description

Sets the stretching mode of this DC to the given mode value and returns the previous mode. The mode argument (BLACKONWHITE, COLORONCOLOR, or WHITEONBLACK) defines which scan lines or columns or both are eliminated by TDC::StretchBlt.


See Also

TDC::GetStretchBltMode

TDC::StretchBlt


TDC::SetSystemPaletteUse

See Also	TDC

Syntax

int SetSystemPaletteUse(int usage);

Description

Changes the usage of this DC's system palette. The usage argument can be SYSPAL_NOSTATIC or SYSPAL_STATIC. Returns the previous usage value.


See Also

TDC::GetSystemPaletteUse


TDC::SetTextAlign

See Also	TDC

Syntax

uint SetTextAlign(uint flags);

Description

Sets the text-alignment flags for this DC. If successful, SetTextAlign returns the previous text-alignment flags; otherwise, it returns GDI_ERROR. The flag values are as listed for the TDC::GetTextAlign function. The text-alignment flags determine how TDC::TextOut and TDC::ExtTextOut align text strings in relation to the first character's screen position.


See Also

TDC::GetTextAlign

TDC::TextOut

TDC::ExtTextOut


TDC::SetTextCharacterExtra

See Also	TDC

Syntax

int SetTextCharacterExtra(int extra);

Description

If successful, sets the current intercharacter spacing to extra, in logical units, for this DC, and returns the previous intercharacter spacing. Otherwise, returns 0. If the current mapping mode is not MM_TEXT, the extra value is transformed and rounded to the nearest pixel.


See Also

TDC::GetTextCharacterExtra


TDC::SetTextColor

See Also	TDC

Syntax

virtual TColor SetTextColor(TColor color);

Description

Sets the current text color of this DC to the given color value. The text color determines the color displayed by TDC::TextOut and TDC::ExtTextOut.


See Also

TDC::GetTextColor

TColor


TDC::SetTextJustification

TDC

Syntax

bool SetTextJustification(int breakExtra, int breakCount);

Description

When text strings are displayed using TDC::TextOut and TDC::ExtTextOut, sets the number of logical units specified in breakExtra as the total extra space to be added to the number of break characters specified in breakCount. The extra space is distributed evenly between the break characters. The break character is usually ASCII 32 (space), but some fonts define other characters. TDC::GetTextMetrics can be used to retrieve the value of the break character.

If the current mapping mode is not MM_TEXT, the extra value is transformed and rounded to the nearest pixel.

SetTextJustification returns true if the call is successful; otherwise, it returns false.


TDC::SetViewportExt

See Also	TDC

Syntax

virtual bool SetViewportExt(const TSize& extent, TSize* oldExtent = 0);

Description

Sets this DC's viewport x- and y-extents to the given extent values. The previous extents are saved in oldExtent. Returns true if the call is successful; otherwise, returns false. The extent value determines the amount of stretching or compression needed in the logical coordinate system to fit the device coordinate system. extent also determines the relative orientation of the two coordinate systems.


See Also

TDC::GetViewportExt

TSize


TDC::SetViewportOrg

See Also	TDC

Syntax

virtual bool SetViewportOrg(const TPoint& origin, TPoint* oldOrg = 0);

Description

Sets this DC's viewport origin to the given origin value, and saves the previous origin in oldOrg. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::GetViewportOrg

TDC::OffsetViewportOrg

TPoint


TDC::SetWindowExt

See Also	TDC

Syntax

virtual bool SetWindowExt(const TSize& extent, TSize* oldExtent = 0);

Description

Sets this DC's window x- and y-extents to the given extent values. The previous extents are saved in oldExtent. Returns true if the call is successful; otherwise, returns false. The extent value determines the amount of stretching or compression needed in the logical coordinate system to fit the device coordinate system. extent also determines the relative orientation of the two coordinate systems.


See Also

TDC::GetWindowExt

TDC::ScaleWindowExt

TSize


TDC::SetWindowOrg

See Also	TDC

Syntax

bool SetWindowOrg(const TPoint& origin, TPoint* oldOrg = 0);

Description

Sets the origin of the window associated with this DC to the given origin value, and saves the previous origin in oldOrg. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::GetWindowOrg

TDC::OffsetWindowOrg

TPoint


TDC::SetWorldTransform

See Also	TDC

Syntax

bool SetWorldTransform(XFORM far& xform);

Description

32-bit only. Sets a two-dimensional linear transformation, given by the xform structure, between world space and page space for this DC. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::ModifyWorldTransform

XFORM struct


TDC::StretchBlt

See Also	TDC

Form 1

bool StretchBlt(int dstX, int dstY, int dstW, int dstH, const TDC& srcDC, int srcX, int srcY, int srcW, int srcH, uint32 rop=SRCCOPY);

Form 2

bool StretchBlt(const TRect& dst, const TDC& srcDC, const TRect& src, uint32 rop=SRCCOPY);

Description

Copies a bitmap from the source DC to a destination rectangle on this DC specified either by upper left-corner coordinates (dstX, dstY), width dstW, and height dstH, or (in the second version) by a TRect object, dst. The source bitmap is similarly specified with (srcX, srcY), srcW, and srcH, or by a TRect object, src. StretchBlt stretches or compresses the source according to the stretching mode currently set in this DC (the destination DC). The raster-operation code, rop, specifies how the colors are combined in output operations that involve a brush, a source bitmap, and a destination bitmap. The rop codes are described in the entry for TDC::MaskBlt


See Also

TDC::MaskBlt

TDC::SetStretchBltMode

TRect


TDC::StretchDIBits

See Also	TDC

Form 1

bool StretchDIBits(const TRect& dst, const TRect& src, const void HUGE* bits, const BITMAPINFO far& bitsInfo, uint16 usage, uint32 rop=SRCCOPY);

Form 2

bool StretchDIBits(const TRect& dst, const TRect& src, const TDib& dib, uint32 rop=SRCCOPY);

Description

Copies the color data from src, the source rectangle of pixels in the given DIB (device-independent bitmap) on this DC, to dst, the destination rectangle. The DIB bits and color data are specified in either the byte array bits and the BITMAPINFO structure bitsInfo or in the TDib object, dib. The rows and columns of color data are stretched or compressed to match the size of the destination rectangle. The usage argument specifies how the bmiColors member of BITMAPINFO is interpreted, as explained in TDC::GetDIBits The raster operation code, rop, specifies how the source pixels, the current brush for this DC, and the destination pixels are combined to produce the new image. See TDC::MaskBlt for a detailed list of rop codes.


See Also

TDC::GetDIBits

TDC::MaskBlt

TDib

TRect

BITMAPINFO struct


TDC::StrokeAndFillPath

See Also	TDC

Syntax

bool StrokeAndFillPath();

Description

32-bit only. Closes any open figures in the current path of this DC, strokes the outline of the path using the current pen, and fills its interior using the current brush and polygon fill mode. Returns true if the call is successful; otherwise, returns false.


See Also

TDC::StrokePath

TDC::BeginPath

TDC::FillPath

TDC::EndPath

TDC::SetPolyFillMode

TBrush

TPen


TDC::StrokePath

See Also	TDC

Syntax

bool StrokePath();

Description

32-bit only. Renders the current, closed path on this DC and uses the DC's current pen.


See Also

TDC::StrokeAndFillPath

TDC::BeginPath


TDC::TabbedTextOut

See Also	TDC

Form 1

bool TabbedTextOut(const TPoint& p, const char far* string, int count, int numPositions, const int far* positions, int tabOrigin);

Form 2

virtual bool TabbedTextOut(const TPoint& p, const char far* string, int count, int numPositions, const int far* positions, int tabOrigin, TSize& size);

Description

Draws up to count characters of the given null-terminated string in the current font on this DC. If count is -1, the whole string is written.

Tabs are expanded according to the given arguments. The positions array specifies numPositions tab stops given in device units. The tab stops must have strictly increasing values in the array. If numPositions and positions are both 0, tabs are expanded to eight times the average character width. If numPositions is 1, all tab stops are taken to be positions[0] apart. tabOrigin specifies the x-coordinate in logical units from which tab expansion will start.

The p argument specifies the logical coordinates of the reference point that is used to align the first character depending on the current text-alignment mode. This mode can be inspected with TDC::GetTextAlign and changed with TDC::SetTextAlign. By default, the current position is neither used nor altered by TabbedTextOut. However, if the align mode is set to TA_UPDATECP, TabbedTextOut ignores the reference point argument(s) and uses/updates the current position as the reference point.

The size argument in the second version of TabbedTextOut reports the dimensions (size.y = height and size.x = width) of the string in logical units.

TabbedTextOut returns true if the call is successful; otherwise, it returns false.


See Also

TDC::TextOut

TDC::GetTextAlign

TDC::SetTextAlign

TPoint

TSize


TDC::TextOut

See Also	TDC

Form 1

virtual bool TextOut(int x, int y, const char far* string, int count = -1);

Form 2

bool TextOut(const TPoint& p, const char far* string, int count = -1);

Description

Draws up to count characters of the given null-terminated string in the current font on this DC. If count is -1 (the default), the entire string is written.

The (x, y) or p arguments specify the logical coordinates of the reference point that is used to align the first character, depending on the current text-alignment mode. This mode can be inspected with TDC::GetTextAlign and changed with TDC::SetTextAlign. By default, the current position is neither used nor altered by TextOut. However, the align mode can be set to TA_UPDATECP, which makes Windows use and update the current position. In this mode, TextOut ignores the reference point argument(s).

TextOut returns true if the call is successful; otherwise, it returns false.


See Also

TDC::ExtTextOut

TDC::GetTextAlign

TDC::SetTextAlign

TPoint


TDC::TextRect

See Also	TDC

Form 1

bool TextRect(int x1, int y1, int x2, int y2);

Form 2

bool TextRect(const TRect& rect);

Form 3

bool TextRect(int x1, int y1, int x2, int y2, TColor color);

Form 4

bool TextRect(const TRect rect, TColor color);

Description

Fills the given rectangle, clipping any text to the rectangle. If no color argument is supplied, the current backgound color is used. If a color argument is supplied, that color is set to the current background color which is then used for filling. TextRect returns true if the call is successful; otherwise, it returns false.


See Also

TDC::SetBkColor

TColor

TRect


TDC::UpdateColors

TDC

Syntax

void UpdateColors();

Description

Updates the client area of this DC by matching the current colors in the client area to the system palette on a pixel-by-pixel basis.


TDC::WidenPath

See Also	TDC

Syntax

bool WidenPath();

Description

32-bit only. Redefines the current, closed path on this DC as the area that would be painted if the path were stroked with this DC's current pen. The current pen must have been created under the following conditions:

If the TPen(int Style, int Width, TColor Color) constructor, or the TPen(const LOGPEN* LogPen) constructor is used, the width of the pen in device units must be greater than 1.

If the TPen(uint32 PenStyle, uint32 Width, const TBrush& Brush, uint32 StyleCount, LPDWORD pSTyle) constructor, or the TPen(uint32 PenStyle, uint32 Width, const LOGBRUSH& logBrush, uint32 StyleCount, LPDWORD pSTyle) constructor is used, the pen must be a geometric pen.

Any Bezier curves in the path are converted to sequences of linear segments approximating the widened curves, so no Bezier curves remain in the path after a WidenPath call.

WidenPath returns true if the call is successful; otherwise, it returns false.


See Also

TDC::FlattenPath

TDC::BeginPath

TPen


TDC::Handle

See Also	TDC

Syntax

TGdiBase::Handle;

Description

The handle of this DC. Uses the base class's handle (TGdiBase::Handle.)


See Also

TDC


TDC::OrgBrush

See Also	TDC

Syntax

HBRUSH OrgBrush;

Description

Handle to the original GDI brush object for this DC. Holds the previous brush object whenever a new brush is selected with SelectObject(brush).


See Also

TDC::SelectObject

TBrush


TDC::OrgFont

See Also	TDC

Syntax

HFONT OrgFont;

Description

Handle to the original GDI font object for this DC. Holds the previous font object whenever a new font is selected with SelectObject(font).


See Also

TDC::SelectObject

TFont


TDC::OrgPalette

See Also	TDC

Syntax

HPALETTE OrgPalette;

Description

Handle to the original GDI palette object for this DC. Holds the previous palette object whenever a new palette is selected with SelectObject(palette).


See Also

TDC::SelectObject

TPalette


TDC::OrgPen

See Also	TDC

Syntax

HPEN OrgPen;

Description

Handle to the original GDI pen object for this DC. Holds the previous pen object whenever a new pen is selected with SelectObject(pen).


See Also

TDC::SelectObject

TPen


TDC::OrgTextBrush

See Also	TDC

Syntax

HBRUSH OrgTextBrush

Description

32-bit only. The handle to the original GDI text brush object for this DC. Stores the previous text brush handle whenever a new brush is selected with SelectObject(text_brush).


See Also

TDC::SelectObject

TBrush


TDC::ShouldDelete

See Also	TDC

Syntax

TGdiBase::ShouldDelete;

Description

Set to true if the handle for this object should be deleted by the destructor; otherwise, set to false.


See Also

~TDC


TDC Protected Constructors

See Also	TDC

Form 1:

TDC();

Form 2:

TDC(HDC handle, TAutoDelete AutoDelete);

Description

Form 1: For use by derived classes only. Calls Init to clear the OrgXXX data members and sets ShouldDelete to true.

Form 2: For use by derived classes only. Constructs a TDC object using an existing DC handle. Calls Init to clear the OrgXXX data members.


See Also

TDC::Init


TDC::CheckValid

TDC

Form 1

TGdiBase::CheckValid( uint resId=IDS_GDIFAILURE)

Form 2

static void CheckValid( HANDLE handle, uint resId=IDS_GDIFAILURE)

Description

Both versions of CheckValid check for a valid GDI object handle. If one is not found a GDI exception is thrown for the given resource id. Both versions use TGdiBase::CheckValid.


TDC::GetAttributeHDC

See Also	TDC

Syntax

virtual HDC GetAttributeHDC() const;

Description

Returns the attributes of the DC object.


See Also

TPrintPreviewDC::GetAttributeHDC


TDC::GetHDC

TDC

Syntax

HDC GetHDC() const;

Description

Returns a handle to the DC.


TDC::Init

See Also	TDC

Syntax

void Init();

Description

Sets OrgBrush, OrgPen, OrgFont, OrgBitmap, and OrgPalette to 0, and sets ShouldDelete to true. This function is for internal use by the TDC constructors.


See Also

TDC constructors

TDC::SelectObject


TDecoratedFrame Class

See Also	OWL Hierarchy	Inheritance

Header File

decframe.h

Description

TDecoratedFrame automatically positions its client window (you must supply a client window) so that it is the same size as the client rectangle. You can add additional decorations like toolbars and status lines to a window.You can create a TDecoratedFrame without a caption bar by clearing all of the bits in the style data member of the TWindowAttr structure. TDecoratedFrame is a streamable class.

For OLE-enabled applications, use TOleFrame, which creates a decorated frame and manages decorations such as toolbars for the main window of an SDI (Single Document Interface) OLE application.

Type definitions

enum TLocation(Top, Bottom, Left, Right);

Public Constructors

TDecoratedFrame(TWindow* parent, const char far *title, TWindow* clientWnd, bool trackMenuSelection = false, TModule* module = 0);

Public Member Functions

void Insert(TWindow& decoration, TLocation = Top);

bool PreProcessMsg(MSG& msg);

TWindow* SetClientWindow(TWindow* clientWnd);

Protected Data Members

uint MenuItemID;

bool TrackMenuSelection;

Protected Member Functions

LRESULT EvCommand(uint Id, HWND hWndCtl, uint notifyCode);

void EvCommandEnable(TCommandEnabler& ce);

void EvEnterIdle(uint source, HWND hWndDlg);

void EvMenuSelect(uint MenuItemId, uint flags, HMENU hMenu);

void EvSize(uint sizeType, TSize& size);

void SetupWindow();

Response Table Entries

EV_ macros and member functions


See Also

TOleFrame


TDecoratedFrame Public Constructor

TDecoratedFrame

Syntax

TDecoratedFrame(TWindow* parent, const char far *title, TWindow* clientWnd, bool trackMenuSelection = false, TModule* module = 0);

Description

Constructs a TDecoratedFrame object with the specified parent window (parent), window caption (title), and module ID. Sets TWindow::Attr.Title to the new title. Passes a pointer to the client window if one is specified. By default set to false, trackMenuSelection controls whether hint text appears at the bottom of the window when a menu item is highlighted.


TDecoratedFrame::TDecoratedFrame:: TLocation enum
TDecoratedFrame:: TLocation enum

TDecoratedFrame

Syntax

enum TLocation (Top, Bottom, Left, Right);

Description

TLocation enum describes Top, Left, Bottom, and Right positions where the decoration can be placed. Insert uses this enum to position the decoration.


TDecoratedFrame::Insert

TDecoratedFrame

Syntax

void Insert (TWindow& decoration, TLocation = Top);

Description

After you specify where the decoration should be placed, Insert adds it just above, below, left, or right of the client window. This process is especially important when there are multiple decorations. Insert looks at the decoration's Attr.Style member and checks the WS_VISIBLE flag to tell whether the decoration should initially be visible or hidden.

To position the decoration, Insert uses TLocation enum, which describes Top, Left, Bottom, and Right positions where the decoration can be placed.


TDecoratedFrame::PreProcessMsg

See Also	TDecoratedFrame

Syntax

bool PreProcessMsg (MSG& msg);

Description

Overrides the virtual function defined in TFrameWindow to give decorations an opportunity to perform mnemonic access preprocessing.


See Also

TFrameWindow::PreProcessMsg

TWindow::PreProcessMsg


TDecoratedFrame::SetClientWindow

TDecoratedFrame

Syntax

TWindow* SetClientWindow(TWindow* clientWnd);

Description

Overrides TFrameWindow's virtual function. Sets the client window to the specified window. Users are responsible for destroying the old client window if they want to remove it.


TDecoratedFrame::MenuItemId

TDecoratedFrame

Syntax

uint MenuItemID;

Description

Specifies the menu item ID.


TDecoratedFrame::TrackMenuSelection

TDecoratedFrame

Syntax

bool TrackMenuSelection;

Description

Specifies whether you want menu selection and help status information visible.


TDecoratedFrame::EvCommand

TDecoratedFrame

Syntax

LRESULT EvCommand(uint Id, HWND hWndCtl, uint notifyCode);

Description

Automates hiding and showing of decorations.


TDecoratedFrame::EvCommandEnable

TDecoratedFrame

Syntax

void EvCommandEnable(TCommandEnabler& ce);

Description

Handles checking and unchecking of menu items that are associated with decorations.


TDecoratedFrame::EvEnterIdle

TDecoratedFrame

Syntax

void EvEnterIdle(uint source, HWND hWndDlg);

Description

Responds to a window message that tells an application's main window that a dialog box or a menu is entering an idle state. EvEnterIdle also handles updating the status bar with the appropriate help message.


TDecoratedFrame::EvMenuSelect

TDecoratedFrame

Syntax

void EvMenuSelect(uint MenuItemId, uint flags, HMENU hMenu);

Description

Responds to user menu selection. If MenuItemId is blank, displays an empty help message; otherwise, it displays a help message with the specified string ID. See EvEnterIdle for a description of how the help message is loaded.


TDecoratedFrame::EvSize

TDecoratedFrame

Syntax

void EvSize(uint sizeType, TSize& size);

Description

Passes a WM_SIZE message to TLayoutWindow.


TDecoratedFrame::SetupWindow

See Also	TDecoratedFrame

Syntax

void SetupWindow();

Description

Calls TLayoutWindow::Layout to size and position the decoration.


See Also

TFrameWindow::SetUpWindow

TWindow::SetUpWindow

TLayoutWindow::Layout


TDecoratedFrame::Response Table Entries

TDecoratedFrame

Response table entry	Member function

EV_WM_ENTERIDLE	EvEnterIdle

EV_WM_MENUSELECT	EvMenuSelect

EV_WM_SIZE	EvSize


TDecoratedMDIFrame Class

OWL Hierarchy	Inheritance

Header File

decmdifr.h

Description

Derived from both TMDIFrame and TDecoratedFrame, TDecoratedMDIFrame is an MDI frame that supports decorated child windows.

TDecorated MDIFrame supports custom toolbars. You can insert one set of decorations (for example, toolbars and rulers) into a decorated frame. When a different set of tools is needed, you can remove the previous set and reinsert another set of decorations. However, be sure to remove all of the unwanted decorations from the adjusted sides (that is, the top, left, bottom, and right) before reinserting a new set.

TDecoratedMDIFrame is a streamable class.

Public Constructor

TDecoratedMDIFrame(const char far *title, TResId menuResId, TMDIClient &clientWnd = *new TMDIClient, bool trackMenuSelection = false, TModule* module = 0);

Protected Member Function

LRESULT DefWindowProc(uint message, WPARAM wParam, LPARAM lParam);

Response Table Entries

TDecoratedMDIFrame Response Table Entries


TDecoratedMDIFrame Public Constructor

TDecoratedMDIFrame

Syntax

TDecoratedMDIFrame(const char far *title, TResId menuResId, TMDIClient &clientWnd = *new TMDIClient, bool trackMenuSelection = false, TModule* module = 0);

Description

Constructs a decorated MDI frame of the specified client window with the indicated menu resource ID. By default, menu hint text is not displayed.


TDecoratedMDIFrame::DefWindowProc

See Also	TDecoratedMDIFrame

Syntax

LRESULT DefWindowProc(uint message, WPARAM wParam, LPARAM lParam);

Description

Overrides TWindow::DefWindowProc . If the message parameter is WM_SIZE, DefWindowProc returns 0; otherwise, DefWindowProc returns the result of calling TMDIFRame::DefWindowProc.


See Also

TMDIFrame::DefWindowProc


TDecoratedMDIFrame::Response Table Entries
TDecoratedMDIFrame Response Table Entries

TDecoratedMDIFrame

The TDecoratedMDIFrame response table has no entries.


TDesktopDC Class

OWL Hierarchy	Inheritance

Header File

dc.h

Description

A DC class derived from TWindowDC, TDesktopDC provides access to the desktop window's client area, which is the screen behind all other windows.

Public Constructor

TDesktopDC();


TDesktopDC Public constructors

TDesktopDC

Syntax

TDesktopDC();

Description

Default constructor for TDesktopDC objects.


TDialog Class

See Also	OWL Hierarchy	Inheritance

Header File

dialog.h

Description

 Typically used to obtain information from a user, a dialog box is a window inside of which other controls such as buttons and scroll bars can appear. Unlike actual child windows which can only be displayed in the parent window's client area, dialog boxes can be moved anywhere on the screen. TDialog objects represent both modal and modeless dialog box interface elements. (A modal dialog box disables operations in its parent window while it is open, and, thus, lets you function in only one window "mode.")

A TDialog object has a corresponding resource definition that describes the placement and appearance of its controls. The identifier of this resource definition is supplied to the constructor of the TDialog object. A TDialog object is associated with a modal interface element by calling its Execute member function and with a modeless interface element by calling its Create member function.

You can use TDialog to build an application that uses a dialog as its main window by constructing your dialog as a TDialog and passing it as the client of a TFrameWindow. Your code might look something like this:

SetMainWindow(new TFrameWindow(0, "title" new TDialog(0, IDD_MYDIALOG)));

ObjectWindows provides three-dimensional (3-D) support for dialog boxes. If you expect to use Microsoft's CTL3D DLL with your application, register your application by calling TApplication::EnableCtl3d. ObjectWindows then automatically forwards the WM_CTLCOLOR message to the CTL3D DLL.

ObjectWindows also provides Borland Windows Custom Controls (BWCC) support for dialog boxes. Unless a custom template is specified, TDialog uses the BWCC templates. (By default, TApplication's member function EnableBWCC enables BWCC support.)

TDialog is a streamable class.

ObjectWindows also encapsulates common dialog boxes that let the user select font, file name, color, print options, and so on. TCommonDialog is the parent class for this group of common dialog box classes.

Public Data Members

TDialogAttr Attr;

bool IsModal;

Public Constructor and Destructor

TDialog(TWindow* parent, TResId resId, TModule* module = 0);

~TDialog();

Public Member Functions

void CloseWindow(int retValue = IDCANCEL);

void CmCancel();

void CmOk();

virtual bool Create();

virtual void Destroy(int retValue = IDCANCEL);

virtual bool DialogFunction(uint message, WPARAM wParam, LPARAM lParam);

virtual HWND DoCreate();

virtual int DoExecute();

void EvClose();

HBRUSH EvCtlColor(HDC hDC, HWND hWndChild, uint ctlType);

virtual bool EvInitDialog(HWND hWndFocus);

void EvPaint();

virtual void EvSetFont(HFONT hfont, bool redraw);

virtual int Execute();

uint GetDefaultId() const;

HWND GetItemHandle(int childId);

bool PerformDlgInit();

bool PreProcessMsg(MSG& msg);

uint32 SendDlgItemMsg(int ChildId, uint16 Msg, uint16 WParam, uint32 LParam);

void SetCaption(const char far* title);

void SetDefaultId(uint Id);

Protected Member Functions

char far* GetClassName();

void GetWindowClass(WNDCLASS& wndClass);

void SetupWindow();

Response Table Entries

EV_ macros and member functions

Structure

struct TDialogAttr {char far* Name;uint32 Param};


See Also

TWindowFlags enum

TCommonDialog


TDialog::Attr

See AlsoTDialog

Syntax

TDialogAttr Attr;

Description

Attr holds the creation attributes of the dialog box (for example, size and style).


See Also

TDialogAttr


TDialog::IsModal

TDialog

Syntax

bool IsModal;

Description

IsModal is true if the dialog box is modal and false if it is modeless.


TDialog Public Constructor and Destructor

See Also	TDialog

Constructor

TDialog(TWindow* parent, TResId resId, TModule* module = 0);

Destructor

~TDialog();

Description

Invokes a TWindow constructor, passing parent and module, and calls DisableAutoCreate to prevent TDialog from being automatically created and displayed along with its parent. TDialog then initializes Title to -1 and sets TDialogAttr.Name using the dialog box's integer or string resource identifier, which must correspond to a dialog resource definition in the resource file. Finally, it initializes TDialogAttr.Param to 0 and sets IsModal to false.

Destructor

If Attr.Name is a string and not an integer resource identifier, this destructor frees memory allocated to Attr.Name, which holds the name of the dialog box.


See Also

TApplication::EnableBWCC

TWindow::~TWindow

TWindow::DisableAutoCreate

TWindow::TWindow

TDialog::Attr


TDialog::CloseWindow

See Also	TDialog

Syntax

void CloseWindow(int retValue = IDCANCEL);

Description

Overrides the virtual function defined by TWindow and conditionally shuts down the dialog box. If the dialog box is modeless, it calls TWindow::CloseWindow. If the dialog box is modal, it calls CanClose. If CanClose returns true, CloseWindow calls TransferData to transfer dialog box data, passing it retValue. The default value of retValue is IDCANCEL.


See Also

TWindow::CloseWindow


TDialog::CmCancel

TDialog

Syntax

void CmCancel();

Description

Automatic response to a click on the Cancel button of the dialog box. Calls Destroy, passing IDCANCEL.

See Also

TDialog::CloseWindow


TDialog::CmOk

See Also	TDialog

Syntax

void CmOk();

Description

Responds to a click on the dialog box's OK button with the identifier IDOK. Calls CloseWindow, passing IDOK.


See Also

TDialog::CloseWindow


TDialog::Create

See Also	TDialog

Syntax

virtual bool Create();

Description

Creates a modeless dialog box interface element associated with the TDialog object. Registers all the dialog's child windows for custom control support. Calls DoCreate to perform the actual creation of the dialog box.

Create returns true if successful. If unsuccessful, Create throws a TXInvalidWindow exception.


See Also

TDialog::Execute

TModule::MakeWindow

TWindow::DisableAutoCreate


TDialog::Destroy

See Also	TDialog

Syntax

virtual void Destroy(int retValue = IDCANCEL);

Description

Destroys the interface element associated with the TDialog object. If the element is a modeless dialog box, Destroy calls TWindow::Destroy. If the element is a modal dialog box, Destroy calls EnableAutoCreate on all child windows. Then Destroy calls the Windows function ::EndDialog, passing retValue as the value returned to indicate the result of the dialog's execution. The default retValue is IDCANCEL.


See Also

TWindow::Destroy

TWindow::EnableAutoCreate


TDialog::DialogFunction

TDialog

Syntax

virtual bool DialogFunction(uint message, WPARAM wParam, LPARAM lParam);

Description

To process messages within the dialog function, your application must override this function. DialogFunction returns true if the message is handled and false if the message is not handled.


TDialog::DoCreate

TDialog

Syntax

virtual HWND DoCreate();

Description

DoCreate is called by Create to performs the actual creation of a modeless dialog box.


TDialog::DoExecute

See Also	TDialog

Syntax

virtual int DoExecute();

Description

DoExecute is called by Execute to perform the actual execution of a modal dialog box.


See Also

TDialog::Execute


TDialog::EvClose

TDialog

Syntax

void EvClose();

Description

Responds to an incoming EvClose message by shutting down the window.


TDialog::EvInitDialog

See Also	TDialog

Syntax

virtual bool EvInitDialog(HWND hWndFocus);

Description

EvInitDialog is automatically called just before the dialog box is displayed. It calls SetupWindow to perform any setup required for the dialog box or its controls.


See Also

TWindow::SetupWindow


TDialog::EvPaint

See Also	TDialog

Syntax

void EvPaint();

Description

EvPaint calls TWindow's general-purpose default processing function, DefaultProcessing, for Windows-supplied painting.


See Also

TWindow::DefaultProcessing


TDialog::EvSetFont

TDialog

Syntax

virtual void EvSetFont(HFONT hfont, bool redraw);

Description

Responds to a request to change a dialog's font.


TDialog::Execute

See Also	TDialog

Syntax

virtual int Execute();

Description

Creates and executes a modal dialog box interface element associated with the TDialog object. If the element is successfully associated, Execute does not return until the TDialog is closed.

Execute performs the following tasks:

1.	Registers this dialog's window class and all of the dialog's child windows.

2.	Calls DoExecute to execute the dialog box.

3.	Checks for exceptions and throws a TXWindow exception if an error occurs.

Execute returns an integer value that indicates how the user closed the modal dialog box. If the dialog box cannot be created, Execute returns -1.


See Also

TModule::ExecDialog

TWindow::DisableAutoCreate

TXWindow


TDialog::GetDefaultId

TDialog

Syntax

uint GetDefaultId() const;

Description

Gets the default resource ID.


TDialog::GetItemHandle

TDialog

Syntax

HWND GetItemHandle(int childId);

Description

Returns the dialog box control's window handle identified by the supplied ID. Because GetItemHandle is now obsolete, new applications should use TWindow::GetDlgItem.


TDialog::PerformDlgInit

TDialog

Syntax

bool PerformDlgInit();

Description

Initializes the dialog box controls with the contents of RT_DLGINIT, the dialog box resource identifier, which describes the appearance and location of the controls (buttons, group boxes, and so on). Returns true if successful; otherwise, returns false.


TDialog::PreProcessMsg

See Also	TDialog

Syntax

bool PreProcessMsg(MSG& msg);

Description

 Overrides the virtual function defined by TWindow in order to perform preprocessing of window messages. If the child window has requested keyboard navigation, PreProcessMsg handles any accelerator key messages and then processes any other keyboard messages.


See Also

TWindow::PreProcessMsg

MSG struct


TDialog::SendDlgItemMsg

TDialog

Syntax

uint32 SendDlgItemMsg(int ChildId, uint16 Msg, uint16 WParam, uint32 LParam);

Description

Sends a window control message, identified by Msg, to the dialog box's control identified by its supplied ID, ChildID. WParam and LParam become parameters in the control message. SendDlgItemMsg returns the value returned by the control, or 0 if the control ID is invalid. This function is obsolete.


TDialog::SetCaption

See Also	TDialog

Syntax

void SetCaption(const char far* title);

Description

 Sets the caption of the dialog box. to the value of the  title parameter.


See Also

TWindow::SetCaption


TDialog::SetDefaultId

TDialog

Syntax

void SetDefaultId(uint Id);

Description

Sets the default resource ID.


TDialog::EvCtlColor

See Also	TDialog

Syntax

HBRUSH EvCtlColor(HDC hDC, HWND hWndChild, uint ctlType);

Description

Passes the handle to the display context for the child window, the handle to the child window, and the default system colors to the parent window. The parent window then uses the display-context handle given in hDC to set the text and background colors of the child window.

If three-dimensional (3-D) support is enabled, EvCtlColor handles the EV_WM_CTLCOLOR message by allowing the CTL3D DLL to process the WM_CTLCOLOR message in order to set the background color and provide a background brush for the window.


See Also

TApplication::EnableCtl3d


TDialog::GetClassName

See Also	TDialog

Syntax

char far* GetClassName();

Description

Overrides the virtual function defined in TWindow and returns the name of the dialog box's default Windows class, which must be used for a modal dialog box. For a modeless dialog box, GetClassName returns the name of the default TWindow. If BWCC is enabled, GetClassName returns BORDLGCLASS.


See Also

TWindow::GetClassName


TDialog::GetWindowClass

See Also	TDialog

Syntax

void GetWindowClass(WNDCLASS& wndClass);

Description

Overrides the virtual function defined in TWindow. Fills WndClass with TDialog registration attributes obtained from an existing TDialog window or from Borland Windows Custom Controls (BWCC) if it is enabled.

If the class style is registered with CS_GLOBALCLASS, you must unregister the class style. You can do this by turning off the style bit. For example:

{

baseclass::GetWindowClass(wndClass);

....

WndClass.style &= ~CS_GLOBALCLASS:

...

}


See Also

TWindow::GetWindowClass

TWindow

WNDCLASS struct


TDialog::SetupWindow

See Also	TDialog

Syntax

void SetupWindow();

Description

Overrides the virtual function defined in TWindow. Sets up the dialog box by calling SetCaption (sets Title) and TWindow::SetupWindow.

If three-dimensional (3-D) support is enabled, SetupWindow calls the CTL3D DLL to register the dialog box.


See Also

TCommonDialog::SetupWindow


TDialog::Response Table Entries

TDialog

Response table entry	Member function

EV_COMMAND (IDCANCEL, CmCancel)	CmCancel

EV_COMMAND (IDOK, CmOk)	CmOk

EV_WM_CTLCOLOR	EvCtlColor

EV_WM_CLOSE	EvClose

EV_WM_PAINT	EvPaint


TDialog::TDialogAttr struct
TDialog class::TDialogAttr struct

OWL Hierarchy	TDialog

Header File

dialog.h

Syntax

struct TDialogAttr {char far* Name;uint32 Param};

Description

Holds a TDialog object's creation attributes, which include the style, appearance, size, and types of controls associated with the dialog box. TDialogAttr contains two data members: Name (the resource id) and Param. These members contain user-defined data used for dialog box creation.

Public Data Members

char far* Name;

uint32 Param;


TDialog::TDialogAttr::Name

TDialogAttr

Syntax

char far* Name;

Description

Name holds the identifier, which can be either a string or an integer resource identifier, of the dialog resource.


TDdialog::TDialogAttr::Param
TDialog::TDialogAttr::Param

TDialogAttr

Syntax

uint32 Param;

Description

Param is used to pass initialization data to the dialog box when it is constructed. You can assign a value to this field in a derived class's constructor. Although any Param-type information passed to the dialog box can be saved as a data member, Param is especially useful if you want to create a dialog box that's implemented by non-ObjectWindows code.

After Param is accepted it is then available in the message response functions (for example, EvInitDialog) associated with WM_INITDIALOG.


TDib Class

OWL Hierarchy	Inheritance

Header File

gdiobjec.h

Description

The class TDib, derived from TGdiObject, represents GDI Device Independent Bitmap (DIB) objects. TDibDCs encapsulate the creation of DCs using DIB.DRV (a GDI driver provided with Windows MME and 3.1). DIBs have no Windows handle; they are just structures containing format and palette information and a collection of bits or pixels. TDib provides a convenient way to work with DIBs like any other GDI object. The memory for the DIB is in one GlobalAlloc'd unit so it can be passed to the Clipboard, OLE 2, and so on.

The TDib Destructor overloads the base Destructor because DIBs are not real GDI objects.

Type Definitions

enum Map{MapFace, MapText, MapShadow, MapHighlight, MapFrame};

Public Constructors and Destructor

TDib(HGLOBAL handle, TAutoDelete autoDelete = NoAutoDelete);

TDib(const TClipboard& clipboard);

TDib(const TDib& dib);

TDib(int width, int height, int nColors, uint16 mode = DIB_RGB_COLORS);

TDib(HINSTANCE instance, TResID resID);

TDib(const char* name);

TDib(const TBitmap& bitmap, const TPalette* pal = 0);

~TDib();

Public Member Functions

operator const BITMAPINFO far*() const;

operator BITMAPINFO far*();

operator const BITMAPINFOHEADER far*() const;

operator BITMAPINFOHEADER far*();

bool ChangeModeToPal(const TPalette& pal);

bool ChangeModeToRGB(const TPalette& pal);

int FindColor(TColor color);

int FindIndex(uint16 index);

const void HUGE* GetBits() const;

void HUGE* GetBits();

TColor GetColor(int entry) const;

const TRgbQuad far* GetColors() const;

TRgbQuad far* GetColors();

uint16 GetIndex(int entry) const;

const uint16 far* GetIndices() const;

uint16 far* GetIndices();

const BITMAPINFO far* GetInfo() const;

BITMAPINFO far* GetInfo();

const BITMAPINFOHEADER far* GetInfoHeader() const;

BITMAPINFOHEADER far* GetInfoHeader();

operator HANDLE() const;

int Height() const;

bool IsOK() const;

bool IsPM() const;

int MapColor(TColor fromColor, TColor toColor, bool doAll = false);

int MapIndex(uint16 fromIndex, Word toIndex, bool doAll = false);

int MapUIColors(uint mapColors, TColor* = 0);

long NumColors() const;

uint16 NumScans() const;

TClipboard& operator <<(TClipboard& clipboard, TDib& dib);

bool operator == (const TDib& other) const

void SetColor(int entry, TColor color);

void SetIndex(int entry, uint16 index);

TSize Size() const;

uint16 StartScan() const;

void ToClipboard(TClipboard& clipboard);

operator const TRgbQuad far*() const;

operator TRgbQuad far*() const;

uint16 Usage() const;

int Width() const;

bool WriteFile(const char* filename);

Protected Data Members

void HUGE* Bits;

int H;

BITMAPINFO far* Info;

bool IsCore;

bool IsResHandle;

uint16 Mode;

long NumClrs;

int W;

Protected Member Functions

void InfoFromHandle();

bool LoadFile(const char* name);

bool LoadResource(HINSTANCE instance, TResID resID);

bool Read(TFile& file, long offBits = 0);


TDib::enum Map
TDib::Map

See Also	TDib

Syntax

enum Map{MapFace, MapText, MapShadow, MapHighlight, MapFrame};

Description

 Enumerates the values for the part of the window whose color is to be set. You can OR these together to control the colors used for face shading on push buttons, the color of a selected control button, the edge shading on push buttons, text on push buttons, the color of the window frame, and the background color of the various parts of a window. The function MapUIColors uses one of these values to map the colors of various parts of a window to a specified color.


See Also

TDib::MapUIColors


TDib::Bits

See Also	TDib

Syntax

void HUGE* Bits;

Description

Bits points into the block of memory pointed to by Info.


See Also

TDib::GetBits


TDib::H

See Also	TDib

Syntax

int H;

Description

The height of this DIB in pixels.


See Also

TDib::Height

TDib::Size

TDib::NumScans


TDib::Info

See Also	TDib

Syntax

BITMAPINFO far* Info;

Description

Locked global allocated block.


See Also

TDib::GetInfo


TDib::IsCore

See Also	TDib

Syntax

bool IsCore;

Description

Set true if this DIB is an old-style PM DIB using core headers; otherwise, set false.


See Also

TDib::isPM


TDib::IsResHandle

TDib

Syntax

bool IsResHandle;

Description

Set true if this DIB is using a resource handle; otherwise, set false.


TDib::Mode

See Also	TDib

Syntax

uint16 Mode;

Description

If Mode is DIB_RGB_Colors, the color table contains 4-byte RGB entries. If Mode is DIB_PAL_COLORS, the color table contains 2-byte indexes into some other palette (such as the system palette). Because either of these two cases might exist, two versions of certain functions (such as GetColors and GetIndices) are required.


See Also

TDib::GetColors

TDib::GetIndices

TDib::Usage


TDib::NumClrs

See Also	TDib

Syntax

long NumClrs;

Description

The number of colors associated with this DIB.


See Also

TDib::NumColors


TDib::W

See Also	TDib

Syntax

int W;

Description

The width of this DIB in pixels.


See Also

TDib::Width

TDib::Size


TDib Public Constructors and Destructor

See Also	TDib

Form 1

TDib(HGLOBAL handle, TAutoDelete autoDelete = NoAutoDelete);

Form 2

TDib(const TClipboard& clipboard);

Form 3

TDib(const TDib& dib);

Form 4

TDib(int width, int height, int nColors, uint16 mode = DIB_RGB_COLORS);

Form 5

TDib(HINSTANCE instance, TResID resID);

Form 6

TDib(const char* name);

Form 7

TDib(const TBitmap& bitmap, const TPalette* pal = 0);

Destructor

~TDib();

Description

Form 1: Creates a TDib object and sets the Handle data member to the given borrowed handle. The ShouldDelete data member defaults to false, ensuring that the borrowed handle will not be deleted when the C++ object is destroyed.

Form 2: Constructs a TDib object with a handle borrowed from the given Clipboard.

Form 3: This public copy constructor creates a complete copy of the given dib object as in:

TDib myDib = yourDib;

Form 4: Creates a DIB object with the given width, height, number of colors, mode values.

Form 5: Creates a DIB object from the resource with the given ID.

Form 6: Creates a DIB object from the given resource file.

Form 7: Creates a DIB object from the given resource bitmap and palette. If pal is 0 (the default), the default palette is used.

Destructor

Overrides the base destructor.


See Also

::GetClipboardData

~TGdiObject

TDib::InfoFromHandle

TDib::LoadFile

TDib::LoadResource

TGdiObject::Handle

TGdiObject::ShouldDelete


TDib::ChangeModeToPal

See Also	TDib

Syntax

bool ChangeModeToPal(const TPalette& pal);

Description

Converts the existing color table in place to use palette relative values. The palette that is passed is used as a reference. Returns true if the call is successful; otherwise returns false.


See Also

TDib::ChangeModeToRGB

TPalette::GetPaletteEntry


TDib::ChangeModeToRGB

See Also	TDib

Syntax

bool ChangeModeToRGB(const TPalette& pal);

Description

Converts the existing color table in place to use absolute RGB values. The palette that is passed is used as a reference. Returns true if the call is successful; otherwise returns false.


See Also

TDib::ChangeModetoPal

TPalette::GetPaletteEntry


TDib::FindColor

See Also	TDib

Syntax

int FindColor(TColor color);

Description

Returns the palette entry for the given color.


See Also

TDib::GetColor

TColor

TDib::SetColor

TDib::MapColor


TDib::FindIndex

See Also	TDib

Syntax

int FindIndex(uint16 index);

Description

Returns the palette entry corresponding to the given index.


See Also

TDib::GetIndex

TDib::SetIndex

TDib::MapIndex


TDib::GetBits

See Also	TDib

Form 1

const void HUGE* GetBits() const;

Form 2

void HUGE* GetBits();

Description

Returns the Bits data member for this DIB.


See Also

TDib::Bits


TDib::GetColor

See Also	TDib

Syntax

TColor GetColor(int entry) const;

Description

Returns the color for the given palette entry.


See Also

TDib::SetColor

TColor

TDib::FindColor

TDib::MapColor


TDib::GetColors

See Also	TDib

Form 1

const TRgbQuad far* GetColors() const;

Form 2

TRgbQuad far* GetColors();

Description

Returns the bmiColors value of this DIB.


See Also

TRgbQuad


TDib::GetIndex

See Also	TDib

Syntax

uint16 GetIndex(int entry) const;

Description

Returns the color index for the given palette entry.


See Also

TDib::SetIndex

TDib::FindIndex,

TDib::MapIndex


TDib::GetIndices

See Also	TDib

Form 1

const uint16 far* GetIndices() const;

Form 2

uint16 far* GetIndices();

Description

Returns the bmiColors indexes of this DIB.


See Also

TDib::GetColors


TDib::GetInfo

See Also	TDib

Form 1

const BITMAPINFO far* GetInfo() const;

Form 2

BITMAPINFO far* GetInfo();

Description

Returns this DIB's Info field. A DIB's BITMAPINFO structure contains information about the dimensions and color of the DIB and specifies an array of data types that define the colors in the bitmap.


See Also

TDib::Info

TDib::GetInfoHeader


TDib::GetInfoHeader

See Also	TDib

Form 1

const BITMAPINFOHEADER far* GetInfoHeader() const;

Form 2

BITMAPINFOHEADER far* GetInfoHeader();

Description

Returns this DIB's bmiHeader field of the BITMAPINFO structure contains information about the color and dimensions of this DIB.


See Also

TDib::Info

TDib::GetInfo

BITMAPINFOHEADER struct


TDib::Height

See Also	TDib

Syntax

int Height() const;

Description

Returns H, this DIB's height.


See Also

TDib::Info


TDib::IsOK

See Also	TDib

Syntax

bool IsOK() const;

Description

Returns false if Info is 0, otherwise returns true. If there is a problem with the construction of the DIB, memory is freed and Info is set to 0. Therefore, using Info is a reliable way to determine if the DIB is constructed correctly.


See Also

TDib constructors

TDib::Info


TDib::IsPM

See Also	TDib

Syntax

bool IsPM() const;

Description

Returns true if IsCore is true; that is, if the DIB is an old-style PM DIB using core headers. Otherwise returns false.


See Also

TDib::IsCore


TDib::MapColor

See Also	TDib

Syntax

int MapColor(TColor fromColor, TColor toColor, bool doAll = false);

Description

Maps the fromColor to the toColor in the current palette of this DIB.

Returns the palette entry for the given color. Returns the palette entry for the toColor argument.


See Also

TDib::GetColor

TColor

TDib::SetColor

TDib::FindColor


TDib::MapIndex

See Also	TDib

Syntax

int MapIndex(uint16 fromIndex, Word toIndex, bool doAll = false);

Description

Maps the fromIndex to the toIndex in the current palette of this DIB.

Returns the palette entry for the toIndex argument.


See Also

TDib::FindIndex

TDib::SetIndex

TDib::GetIndex


TDib::MapUIColors

See Also	TDib

Syntax

void MapUIColors(uint mapColors, TColor* bkColor = 0 )

Description

Maps the UI colors to the value specified in the parameter, mapColors, which is one of the values of the Map enum. Use this function to get the colors for the face shading on push buttons, the highlighting for a selected control button, the text on push buttons, the shade of the window frame and the background color.


See Also

TDib::Map enum


TDib::NumColors

See Also	TDib

Syntax

long NumColors() const;

Description

Returns NumClrs, the number of colors in this DIB's palette.


See Also

TDib::Info


TDib::NumScans

See Also	TDib

Syntax

uint16 NumScans() const;

Description

Returns the number of scans in this DIB.


See Also

TDib::StartScan


TDib::operator <<

See Also	TDib

Syntax

TClipboard& operator <<(TClipboard& clipboard, TDib& dib);

Description

Writes the given dib to the given clipboard. Returns a reference to the resulting Clipboard, allowing the normal chaining of <<.


See Also

TClipboard


TDib::operator BITMAPINFO()

See Also	TDib

Form 1

operator const BITMAPINFO far*() const;

Form 2

operator BITMAPINFO far*();

Description

Typecasts this DIB by returning a pointer to its bitmap information structure (BITMAPINFO) which contains information about this DIB's color format and dimensions (size, width, height, resolution, and so on).


See Also

TDib::GetInfo

BITMAPINFO struct


TDib::operator BITMAPINFOHEADER()

See Also	TDib

Form 1

operator const BITMAPINFOHEADER far*() const;

Form 2

operator BITMAPINFOHEADER far*();

Description

Typecasts this DIB by returning a pointer to its bitmap info header.


See Also

TDib::GetInfoHeader

BITMAPINFOHEADER struct


TDib::operator HANDLE()

See Also	TDib

Syntax

operator HANDLE() const;

Description

Typecasts this DIB by returning its Handle.


See Also

TGdiObject::Handle


TDib::operator ==

See Also	TDib

Syntax

bool operator ==(const TDib& other) const;

Description

 Compares two handles and returns true if this DIB's handle equals the other (other) DIB's handle.


See Also

Tdib::Handle


TDib::operator TRgbQuad()

See Also	TDib

Form 1

operator const TRgbQuad far*() const;

Form 2

operator TRgbQuad far*() const;

Description

Typecasts this DIB by returning a pointer to its colors structure.


See Also

TDib::GetColors

TRgbQuad


TDib::SetColor

See Also	TDib

Syntax

void SetColor(int entry, TColor color);

Description

Sets the given color for the given palette entry.


See Also

TDib::GetColor

TColor

TDib::MapColor

TDib::FindColor


TDib::SetIndex

See Also	TDib

Syntax

void SetIndex(int entry, uint16 index);

Description

Sets the given index for the given entry.


See Also

TDib::GetIndex

TDib::FindIndex

TDib::MapIndex


TDib::Size

See Also	TDib

Syntax

TSize Size() const;

Description

Returns TSize(W,H), the size of this DIB.


See Also

TDib::Info

TSize


TDib::StartScan

See Also	TDib

Syntax

uint16 StartScan() const;

Description

Returns the DIB's starting scan line.


See Also

TDib::numScans


TDib::ToClipboard

See Also	TDib

Syntax

void ToClipboard(TClipboard& clipboard);

Description

Puts this DIB onto the specified Clipboard.


See Also

TClipboard


TDib::Usage

See Also	TDib

Syntax

uint16 Usage() const;

Description

Returns the Mode for this DIB. This value tells GDI how to treat the color table.


See Also

TDib::Mode


TDib::Width

See Also	TDib

Syntax

int Width() const;

Description

Returns W, the DIB width.


See Also

TDib::Info


TDib::WriteFile

TDib

Syntax

bool WriteFile(const char* filename);

Description

Returns true if the call is successful; otherwise returns false.


TDib::InfoFromHandle

See Also	TDib

Syntax

void InfoFromHandle();

Description

Locks this DIB's handle and extracts the remaining data member values from the DIB header.


See Also

TDib::GetInfoHeader


TDib::LoadFile

See Also	TDib

Syntax

bool LoadFile(const char* name);

Description

Loads this DIB from the given file name. Returns true if the call is successful; otherwise returns false.


See Also

TDib::LoadResource

TDib constructors


TDib::LoadResource

See Also	TDib

Syntax

bool LoadResource(HINSTANCE instance, TResID resID);

Description

Loads this DIB from the given resource and returns true if successful.


See Also

TDib::LoadFile

TDib constructors


TDib::Read

See Also	TDib

Syntax

bool Read(TFile& file, long offBits = 0);

Description

Reads data to this DIB, starting at offset offBits, from any file, BMP, or resource. Returns true if the call is successful; otherwise returns false.


See Also

TDib::LoadFile


TDibDC Class

OWL Hierarchy	Inheritance

Header File

dc.h

Description

A DC class derived from TDC, TDibDC provides access to device-independent bitmaps (DIBs).

Public Constructors

TDibDC(const TDib& dib);


TDibDC Public Constructors

See Also	TDibDC

Syntax

TDibDC(const TDib& dib);

Description

Creates a TDibDC object with the data provided by the given TDib object.


See Also

classTDib

TDC::TDC


TDocument Class

OWL Hierarchy	Inheritance

Header File

docview.h

Description

An abstract base class, TDocument is the base class for all document objects and serves as an interface between the document, its views, and the document manager (TDocManager class). TDocument creates, destroys, and sends messages about the view. For example, if the user changes a document, TDocument tells the view that the document has been updated. The DEFINE_DOC_TEMPLATE_CLASS macro associates a document with its views.

In order to send messages to its associated views, the document maintains a list of all the views existing for that document and communicates with the views using ObjectWindows event-handling mechanism. Rather than using the function SendMessage, the document accesses the view's event table. The views can update the document's data by calling the member functions of the particular document. Views can also request streams, which are constructed by the document.

Both documents and views have lists of properties for their applications to use. When documents and views are created or destroyed, messages are sent to the application, which can then query the properties to determine how to process the document or view. It is the document manager's responsibility to determine if a particular view is appropriate for the given document.

Because the property attribute functions are virtual, a derived class (which is called first) might override the properties defined in a base class. Each derived class must implement its own property attribute types of either string or binary data. If the derived class duplicates the property names of the parent class, it should provide the same behavior and data type as the parent.

In order to add persistence to documents, TDocument contains several virtual functions (for example, InStream and OutStream) that support streaming. Your derived classes need to override these functions in order to read and write data.

Although documents are usually associated with files, they do not necessarily have to be files; they can also consist of database tables, mail systems, fax or modem transmissions, disk directories, and so on.

Public Data Members

List ChildDoc;

void far* Tag;

Type Definitions

enum TDocProp {PrevProperty = 0, DocumentClass, TemplateName, ViewCount, StoragePath, DocTitle, NextProperty};

Public Constructor and Destructor

TDocument(TDocument* parent = 0);

virtual ~TDocument();

Public Member Functions

virtual bool CanClose();

virtual bool Close();

virtual bool Commit(bool force = false);

virtual int FindProperty(const char far* name);

TDocManager& GetDocManager();

const char far* GetDocPath();

int GetOpenMode;

TDocument* GetParentDoc():

virtual int GetProperty(int index, void far* dest, int textlen=0);

TDocTemplate* GetTemplate();

const char far* GetTitle();

bool HasFocus(HWND hwnd);

bool InitDoc();

virtual TInStream* InStream(int mode, const char far* strmId=0);

virtual bool IsDirty();

bool IsEmbedded();

virtual bool IsOpen();

TStream* NextStream(const TStream* strm);

TView* NextView(const TView* view);

bool NotifyViews(int event, long item=0, TView* exclude=0);

virtual bool Open(int mode, const char far* path = 0);

virtual TOutStream* OutStream(int mode, const char far* strmId = 0);

virtual uint PostError(uint sid, uint choice = MB_OK);

virtual int PropertyCount();

virtual int PropertyFlags(int index);

virtual const char* PropertyName(int index);

TView* QueryViews(int event, long item=0, TView* exclude=0);

virtual bool Revert( bool clear = false);

virtual TDocument& RootDocument();

void SetDocManager(TDocManager& dm);

virtual bool SetDocPath(const char far* path);

void SetEmbedded(bool embedded = true);

void SetOpenMode(int mode);

virtual bool SetProperty(int index, const void far* src);

bool SetTemplate(TDocTemplate* tpl);

virtual void SetTitle(const char far* title);

Protected Data Member

bool DirtyFlag;

bool Embedded;

Protected Member Functions

virtual void AttachStream(TStream& strm);

virtual void DetachStream(TStream& strm);


TDocument::ChildDoc

TDocument

Syntax

List ChildDoc;

Description

The list of child documents associated with this document.


TDocument::TDocProp enum

TDocument

Syntax

enum TDocProp{ PrevProperty = 0, DocumentClass, TemplateName, ViewCount, StoragePath, DocTitle, NextProperty, };

Description

These property values, defined for TDocument, are available in classes derived from TDocument. PrevProperty and NextProperty are delimiters for every document's property list.


TDocument::Tag

TDocument

Syntax

void far* Tag;

Description

Holds a pointer to the application-defined data. Typically, you can use Tag to install a pointer to your own application's associated data structure. Tag, which is initialized to 0 at the time a TDocument object is constructed, is not otherwise used by the document view classes.


TDocument Public Constructor and Destructor

TDocument

Constructor

TDocument(TDocument* parent = 0);

Description

Although you do not create a TDocument object directly, you must call the constructor when you create a derived class. parent points to the parent of the new document. If no parent exists, parent is 0.

Destructor

virtual ~TDocument();

Destructor

Deletes a TDocument object. Normally, Close is called first. TDocument's destructor destroys all children and closes all open streams. If this is the last document that used the template, it closes the object's template and any associated views, deletes the object's stream, and removes itself from the parent's list of children if a parent exists. If there is no parent, it removes itself from the document manager's document list.


TDocument::CanClose

TDocument

Syntax

virtual bool CanClose();

Description

Checks to see if all child documents can be closed before closing the current document. If any child returns false, CanClose returns false and aborts the process. If all children return true, calls TDocManager::FlushDoc. If FlushDoc finds that the document has been changed but not saved, it displays a message asking the user to either save the document, discard any changes, or cancel the operation. If the document has not been changed and all children's CanClose functions return true, this CanClose function returns true.


TDocument::Close

TDocument

Syntax

virtual bool Close();

Description

Closes the document but does not delete or detach the document. Before closing the document, Close checks any child documents and tries to close them before closing the parent document. Even if you write your own Close function, call TDocument's version to ensure that all child documents are checked before the parent document is closed.


TDocument::Commit

TDocument

Syntax

virtual bool Commit(bool force = false);

Description

Saves the current data to storage. When a file is closed, the document manager calls either Commit or Revert. If force is true, all data is written to storage. Commit checks any child documents and commits their changes to storage also. Before the current data is saved, all child documents must return true. If all child documents return true, Commit flushes the views for operations that occurred since the last time the view was checked. After all data for the document is updated and saved, Commit returns true.


TDocument::FindProperty

See Also	TDocument

Syntax

virtual int FindProperty(const char far* name);

Description

Gets the property index, given the property name (name). Returns either the integer index number that corresponds to the name or 0 if the name isn't found in the list of properties.


See Also

pfxxxx property attribute constants

TDocument::PropertyName


TDocument::GetDocManager

TDocument

Syntax

TDocManager& GetDocManager();

Description

Returns a pointer to the current document manager.


TDocument::GetDocPath

TDocument

Syntax

const char far* GetDocPath();

Description

Returns the directory path for the document. This might change the SaveAs operation.


TDocument::GetOpenMode

See Also	TDocument

Syntax

int GetOpenMode;

Description

Gets the mode and protection flag values for the current document.


See Also

TDocument::SetOpenMode


TDocument::GetParentDoc

TDocument

Syntax

TDocument* GetParentDoc():

Description

Returns either the parent document of the current document or 0 if there is no parent document.


TDocument::GetProperty

See Also	TDocument

Syntax

virtual int GetProperty(int index, void far* dest, int textlen=0);

Description

Returns the total number of properties for this document, where index is the property index, dest contains the property data, and textlen is the size of the array. If textlen is 0, property data is returned as binary data; otherwise, property data is returned as text data.


See Also

pfxxxx property attribute constants

TDocument::SetProperty


TDocument::GetTemplate

TDocument

Syntax

TDocTemplate* GetTemplate();

Description

Gets the template used for document creation. The template can be changed during a SaveAs operation.


TDocument::GetTitle

TDocument

Syntax

CONST CHAR FAR* GetTitle();

Description

Returns the title of the document.


TDocument::HasFocus

TDocument

Syntax

bool HasFocus(HWND hwnd);

Description

Used by the document manager, HasFocus returns true if this document's view has focus. hwnd is a handle to the document. to determine if the document contains a view with a focus.


focus

The view associated with this document is the active view.


TDocument::InitDoc

See Also	TDocument

Syntax

virtual bool InitDoc();

Description

 A virtual method that is overridden by TOleDocument::InitDoc. You can use this function to prepare the document before the view is constructed and before the dnCreate event, which indicates that the document has been created and is posted.


See Also

dnxxxx Document Message enum


TDocument::InStream

See Also	TDocument

Syntax

virtual TInStream* InStream(int mode, const char far* strmId=0);

Description

Generic input for the particular storage medium, InStream returns a pointer to a TInStream. mode is a combination of the ios bits defined in iostream.h. See the document open mode constants for a list of the open modes. Used for documents that support named streams, strmId is a pointer to the name of a stream. Override this function to provide streaming for your document class.


See Also

TDocument::OutStream


TDocument::IsDirty

TDocument

Syntax

virtual bool IsDirty();

Description

Returns true if the document or one of its views has changed but has not been saved.


TDocument::IsEmbedded

See Also	TDocument

Syntax

virtual bool IsEmbedded();

Description

Returns true if the document is embedded in an OLE 2 container.


See Also

TDocument::SetEmbedded


TDocument::IsOpen

TDocument

Syntax

virtual bool IsOpen();

Description

Checks to see if the document has any streams in its stream list. Returns false if no streams are open; otherwise, returns true.


TDocument::NextStream

TDocument

Syntax

TStream* NextStream(const TStream* strm);

Description

Gets the next entry in the stream. Holds 0 if none exists.


TDocument::NextView

TDocument

Syntax

TView* NextView(const TView* view);

Description

Gets the next view in the list of views. Holds 0 if none exists.


TDocument::NotifyViews

TDocument

Syntax

bool NotifyViews(int event, long item=0, TView* exclude=0);

Description

Notifies the views of the current document and the views of any child documents of a change. In contrast to QueryViews, NotifyViews sends notification of an event to all views and returns true if any views returned a true result. The event, EV_OWLNOTIFY, is sent with an event code, which is private to the particular document and view class, and a long argument, which can be cast appropriately to the actual type passed in the argument of the response function.


TDocument::Open

See Also	TDocument

Syntax

virtual bool Open(int mode, const char far* path = 0);

Description

Opens the document using the path specified by DocPath. Sets OpenMode to mode. TDocument::Open always returns true and actually performs no actions. Other classes override this function to open specified file documents and views.


See Also

TFileDocument::Open


TDocument::OutStream

See Also	TDocument

Syntax

virtual TOutStream* OutStream(int mode, const char far* strmId = 0);

Description

Generic output for the particular storage medium, OutStream returns a pointer to a TOutStream. mode is a combination of the ios bits defined in iostream.h. Used for documents that support named streams, strmId points to the name of the stream. TDocument::OutStream version always returns 0. Override this function to provide streaming for your document class.


See Also

TDocument::InStream


TDocument::PostError

See Also	TDocument

Syntax

virtual uint PostError(uint sid, uint choice = MB_OK);

Description

Posts the error message passed as a string resource ID in sid. choice is one or more of the MB_Xxxx style constants.


See Also

TDocManager::PostDocError

MB_Xxxx message constants


TDocument::PropertyCount

See Also	TDocument

Syntax

virtual int PropertyCount();

Description

Gets the total number of properties for the TDocument object. Returns NextProperty -1.


See Also

pfxxxx property attribute constants


TDocument::PropertyFlags

See Also	TDocument

Syntax

virtual int PropertyFlags(int index);

Description

Returns the attributes of a specified property given the index (index) of the property whose attributes you want to retrieve.


See Also

pfxxxx property attribute constants

TDocument::FindProperty

TDocument::PropertyName


TDocument::PropertyName

See Also	TDocument

Syntax

virtual const char* PropertyName(int index);

Description

Returns the name of the property given the index value (index).


See Also

pfxxxx property attribute constants

TDocument::FindProperty


TDocument::QueryViews

TDocument

Syntax

TView* QueryViews(int event, long item=0, TView* exclude=0);

Description

Queries the views of the current document and the views of any child documents about a specified event, but stops at the first view that returns true. In contrast to NotifyViews, QueryViews returns a pointer to the first view that responded to an event with a true result. The event, EV_OWLNOTIFY, is sent with an event code (which is private to the particular document and view class) and a long argument (which can be cast appropriately to the actual type passed in the argument of the response function).


TDocument::Revert

TDocument

Syntax

virtual bool Revert( bool clear = false);

Description

Performs the reverse of Commit and cancels any changes made to the document since the last commit. If clear is true, data is not reloaded for views. Revert also checks all child documents and cancels any changes if all children return true. When a file is closed, the document manager calls either Commit or Revert. Returns true if the operation is successful.


TDocument::RootDocument

TDocument

Syntax

virtual TDocument& RootDocument();

Description

Returns the this pointer as the root document.


TDocument::SetDocManager

TDocument

Syntax

void SetDocManager(TDocManager& dm);

Description

Sets the current document manager to the argument dm.


TDocument::SetDocPath

TDocument

Syntax

virtual bool SetDocPath(const char far* path);

Description

Sets the document path for Open and Save operations.


TDocument::SetEmbedded

See Also	TDocument

Syntax

virtual bool SetEmbedded();

Description

Marks the document as being embedded in an OLE 2 container. Typically, this happens when the server is created and when the factory template class creates the component.


See Also

TDocument::IsEmbedded

Factory template classes


TDocument::SetOpenMode

See Also	TDocument

Syntax

void SetOpenMode(int mode);

Description

Sets the mode and protection flag values for the current document.


See Also

TDocument::GetOpenMode


TDocument::SetProperty

See Also	TDocument

Syntax

virtual bool SetProperty(int index, const void far* src);

Description

Sets the value of the property, given index, the index value of the property, and src, the data type (either binary or text) to which the property must be set.


See Also

pfxxxx property attribute constants

TDocument::GetProperty


TDocument::SetTemplate

TDocument

Syntax

bool SetTemplate(TDocTemplate* tpl);

Description

Sets the document template. However, if the template type is incompatible with the file, the document manager will refuse to save the file as this template type.


TDocument::SetTitle

TDocument

Syntax

virtual void SetTitle(const char far* title);

Description

Sets the title of the document.


TDocument::DirtyFlag

TDocument

Syntax

bool DirtyFlag;

Description

Indicates that unsaved changes have been made to the document. Views can also independently maintain their local disk status.


TDocument::Embedded

TDocument

Syntax

bool Embedded;

Description

Indicates whether the document is embedded.


TDocument::AttachStream

TDocument

Syntax

virtual void AttachStream(TStream& strm);

Description

Called from TStream's constructor, AttachStream attaches a stream to the current document.


TDocument::DetachStream

TDocument

Syntax

virtual void DetachStream(TStream& strm);

Description

Called from TStream's destructor, DetachStream detaches the stream from the current document.


TDocument::List Nested Class

TDocument

Header File

docview.h

The TDocument::List nested class encapsulates the chain of documents. It allows addition, removal, and destruction of documents from the document list.

Public Constructor and Destructor

List();

~List();

Public Member Functions

void Destroy();

bool Insert(TDocument* doc);

TDocument* Next(const TDocument* doc);

bool Remove(TDocument* doc);


TDocument::List Public Constructor and Destructor

TDocument::List

Constructor

List();

Description

Constructs a TDocument::List object.

Destructor

~List();

Description

Destroys a TDocument::List object.


TDocument::Destroy
TDocument::List::Destroy

TDocument::List

Syntax

void Destroy();

Description

Deletes all documents.


TDocument::Insert
TDocument::List::Insert

TDocument::List

Syntax

bool Insert(TDocument* doc);

Description

Inserts a new document into the document list. Fails if the document already exists.


TDocument::Next
TDocument::List::Next

TDocument::List

Syntax

TDocument* Next(const TDocument* doc);

Description

 If the  doc  parameter is 0,  Next  returns the first document in the list of documents.


TDocument::Remove
TDocument::List::Remove

TDocument::List

Syntax

bool Remove(TDocument* doc);

Description

Removes a document from the document list.


TDocManager Class

OWL Hierarchy	Inheritance

Header File

docmanag.h

Description

TDocManager creates a document manager object that manages the list of current documents and registered templates, handles standard file menu commands, and displays the user-interface for file and view selection boxes. To provide support for documents and views, an instance of TDocManager must be created by the application and attached to the application.

The document manager normally handles events on behalf of the documents by using a response table to process the standard CM_FILENEW, CM_FILEOPEN, CM_FILECLOSE, CM_FILESAVE, CM_FILESAVEAS, CM_FILEREVERT, CM_FILEPRINT, CM_FILEPRINTERSETUP,  and CM_VIEWCREATE and CM_VIEWCREATE File menu commands. In response to a CM_FILENEW or a CM_FILEOPEN command, the document manager creates the appropriate document based on the user's selections. In response to the other commands, the document manager determines which of the open documents contains the view associated with the window that has focus. The menu commands are first sent to the window that is in focus and then through the parent window chain to the main window and finally to the application, which forwards the commands to the document manager.

When you create a TDocManager or a derived class, you must specify that it has either a multi-document (dmMDI) or single-document (dmSDI) interface. In addition, if you want the document manager to handle the standard file commands, you must OR dmMDI or dmSDI with dmMenu.

You can also enable or disable the document manager menu options by passing dmSaveEnable or dmNoRevert in the constructor. If you want to enable the File|Save menu option if the document is unmodified, pass the dmSaveEnable flag in the constructor. To disable the "Revert to Saved" menu option, pass dmNoRevert in the constructor.

When the application directly creates a new document and view, it can attach the view to its frame window, create MDI children, float the window, or create a splitter. However, when the document manager creates a new document and view from the File|Open or File|New menu selection, the application doesn't control the process. To give the application control, the document manager sends messages after the new document and view are successfully created. Then, the application can use the information contained in the template to determine how to install the new document or view object.

Public Data Members

TDocument::List DocList;

Public Constructor and Destructor

TDocManager(int mode, TDocTemplate*& templateHead = DocTemplateStaticHead);

TDocManager(int mode,TApplication* app, TDocTemplate*& templateHead = DocTemplateStaticHead);

virtual ~TDocManager();

Public Member Functions

void AttachTemplate(TDocTemplate&);

virtual void CmFileClose();

virtual void CmFileNew();

virtual void CmFileOpen();

virtual void CmFileRevert();

virtual void CmFileSave();

virtual void CmFileSaveAs();

virtual void CmViewCreate();

virtual TDocument* CreateAnyDoc(const char far* path, long flags= 0);

virtual TView* CreateAnyView(TDocument& doc, long flags= 0);

TDocument* CreateDoc(TDocTemplate* tpl, const char far *, TDocument* parent, long flags = 0);

TView* CreateView(TDocument* doc);

void DeleteTemplate(TDocTemplate&);

bool EvCanClose();

void EvPreProcessMenu(HMENU hmenu);

void EvWakeUp();

TDocument* FindDocument(const char far* path);

virtual bool FlushDoc(TDocument& doc);

TApplication* GetApplication();

virtual TDocument* GetCurrentDoc();

TDocTemplate* GetNextTemplate(TDocTemplate* tpl);

TDocument* InitDoc(TDocument* doc, const char far* path, long flags);

bool IsFlagSet(int Flag);

TDocTemplate* MatchTemplate(const char far* path);

virtual uint PostDocError(TDocument& doc, uint sid, uint choice = MB_OK);

virtual void PostEvent(int id, TDocument& doc);

virtual void PostEvent(int id, TView& view);

void RefTemplate(TDocTemplate&);

virtual TDocTemplate* SelectAnySave(TDocument& doc);

bool SelectSave(TDocument& doc);

void UnRefTemplate(TDocTemplate&);

Protected Member Functions

virtual int SelectDocPath(TDocTemplate** tpllist, int tplcount, char far* path, int buflen, long flags, bool save=false);

virtual int SelectDocType(TDocTemplate** tpllist, int tplcount);virtual int SelectViewType(TDocTemplate** tpllist, int tplcount);

Response Table Entries

EV_ macros and member functions


TDocManager::DocList

TDocManager

Syntax

TDocument::List DocList;

Description

Holds the list of attached documents, or 0 if no documents exist.


TDocManager Public Constructor and Destructor

See Also	TDocManager

Constructors

Syntax 1

TDocManager(int mode, TDocTemplate*& templateHead = DocTemplateStaticHead);

Description

Constructs a TDocManager object that supports either single (SDI) or multiple (MDI) open documents depending on the application. The mode parameter is set to one of the following: dmMenu, dmMDI, dmSDI, dmSaveEnable, or dmNoRevert. To install the standard TDocManager File menu commands, you must OR dmMDI or dmSDI with dmMenu. For example,

DocManager = new TDocManager(DocMode | dmMenu);

The document manager can then use its menu and response table to handle these events. If you do not specify the dmMenu parameter, you must provide the menu and functions to handle these commands. However, you can still use your application object's DocManager data member to access the document manager's functions.

Syntax 2

TDocManager(int mode, TApplication* app, TDocTemplate*& templateHead = DocTemplateStaticHead);

Description

The constructor performs the same operations as the first constructor. The additional app  parameter, however, points to the application associated with this document.

Destructor

virtual ~TDocManager();

Description

Destroys a TDocManager object removes attached documents templates. The constructor resets TDocTemplate::DocTemplateStaticHead to point to the head of the static template list.


See Also

dmxxxx document manager mode constants


TDocManager::AttachTemplate

TDocManager

Syntax

void AttachTemplate(TDocTemplate& );

Description

Inserts a template into the chain of templates.


TDocManager::CmFileClose

TDocManager

Syntax

virtual void CmFileClose();

Description

Responds to a file close message. Tests to see if the document has been changed since it was last saved, and if not, prompts the user to confirm the save operation.


TDocManager::CmFileNew

See Also	TDocManager

Syntax

virtual void CmFileNew();

Description

Calls CreateAnyDoc with no path specified.


See Also

dtxxxx document template constants


TDocManager::CmFileOpen

TDocManager

Syntax

virtual void CmFileOpen();

Description

Lets the user select a registered template from the list displayed in the dialog box. Calls CreateAnyDoc.


TDocManager::CmFileRevert

TDocManager

Syntax

virtual void CmFileRevert();

Description

Reverts to the previously saved document. Does not revert if the document has not been changed since last save; that is, if the document's IsDirty function returns false.


TDocManager::CmFileSave

See Also	TDocManager

Syntax

virtual void CmFileSave();

Description

Responds to a file save message. Sets doc to the current document.  CmFileSave checks IsDirty only if the dmSaveEnable flag was not specified. Calls PostDocError with IDS_NOTCHANGED if dmSaveEnable was NOT specified and IsDirty returns false.


See Also

IDS_xxxx Document String ID constants


TDocManager::CmFileSaveAs

TDocManager

Syntax

virtual void CmFileSaveAs();

Description

Prompts the user to enter a new name for the document and saves the document to that file.


TDocManager::CmViewCreate

TDocManager

Syntax

virtual void CmViewCreate();

Description

Creates a document view based on the view name of the current document. If more than one template exists for the document, CmViewCreate allows the user to select the type of view from the template list.


TDocManager::CreateAnyDoc

See Also	TDocManager

Syntax

virtual TDocument* CreateAnyDoc(const char far* path, long flags= 0);

Description

Creates a document based on the directory path and the specified template. The parameter flags, one of the document template constants, determines how the document template is created. If path is 0 and this is not a new document (the flag dtNewDoc is not set), it displays a dialog box. If path is 0 and dtNewDoc is not set and more than one template exists, CreateAnyDoc displays a dialog box and a list of templates.


See Also

TDocTemplate::CreateDoc

dtxxxx document template constants


TDocManager::CreateAnyView

See Also	TDocManager

Syntax

virtual TView* CreateAnyView(TDocument& doc, long flags= 0);

Description

Creates a document view based on the directory path and specified template. The parameter flags, one of the document template constants, determines how the document template is created.


See Also

TDocument

TDocTemplate::CreateView

dtxxxx document template constants


TDocManager::CreateDoc

See Also	TDocManager

Syntax

TDocument* CreateDoc(TDocTemplate* tpl, const char far *, TDocument* parent, long flags = 0);

Description

CreateDoc creates a document based on the directory path and the specified template. The flags parameter contains one of the document template constants that determines how the document is created.


See Also

TDocument

TDocTemplate::CreateView

dtxxxx document template constants


TDocManager::CreateView

See Also	TDocManager

Syntax

TView* CreateView(TDocument* doc);

Description

Creates a view of the specified document.


See Also

TDocTemplate::CreateView

dtxxxx document template constants


TDocManager::DeleteTemplate

See Also	TDocManager

Syntax

void DeleteTemplate(TDocTemplate&);

Description

Removes a template from the list of templates attached to the document.


See Also

TDocManager::RefTemplate


TDocManager::EvCanClose

TDocManager

Syntax

bool EvCanClose();

Description

Checks to see if all child documents can be closed before closing the current document. If any child returns false,  returns false and aborts the process. If all children return true, EvCanClose calls TDocManager::FlushDoc for each document. If FlushDoc finds that the document is dirty, it displays a message asking the user to save the document, discard any changes, or cancel the operation. If the document is not dirty and CanClose returns true, EvCanClose returns true.


TDocManager::EvPreProcessMenu

See Also	TDocManager

Syntax

void EvPreProcessMenu(HMENU hmenu);

Description

Called from MainWindow, EvPreProcessMenu loads and deletes a menu at the position specified by MF_POSITION or MF_POPUP. Your application can call EvPreProcessMenu to process the main window's menu before it is displayed.


See Also

TApplication::PreProcessMenu


TDocManager::EvWakeUp

TDocManager

Syntax

void EvWakeUp();

Description

Used only after streaming in the doc manager, EvWakeUp allows for the windows to be created after the streaming has occurred.


TDocManager::FindDocument

See Also	TDocManager

Syntax

TDocTemplate* FindDocument(const char far* path);

Description

Returns the first document whose pattern matches the given file name. If no document is compatible with the supplied file name, or if the document is open already, it returns 0.


See Also

TDocTemplate


TDocManager::FlushDoc

See Also	TDocManager

Syntax

virtual bool FlushDoc(TDocument& doc);

Description

Updates the document with any changes and prompts the user for confirmation of updates.


See Also

TDocument


TDocManager::GetApplication

See Also	TDocManager

Syntax

TApplication* GetApplication();

Description

Returns the current application.


See Also

TApplication


TDocManager::GetCurrentDoc

See Also	TDocManager

Syntax

virtual TDocument* GetCurrentDoc();

Description

Calls TWindow::GetFocus to determine the window with the focus. Searches the list of documents and returns the document that contains the view with the focus. Returns 0 if no document has a view with focus.


See Also

TDocument


TDocManager::GetNextTemplate

See Also	TDocManager

Syntax

TDocTemplate* GetNextTemplate(TDocTemplate* tpl);

Description

Returns the next document template.


See Also

TDocTemplate


TDocManager::InitDoc

See Also	TDocManager

Syntax

TDocument* InitDoc(TDocument* doc, const char far* path, long flags)

Description

Initializes the documents, the directory path for the document, and the dtxxxx document flag values (such as  dtNewDoc ) used to create document templates.

See Also

TDocTemplate

dt Document View Constants


TDocManager::IsFlagSet

See Also	TDocManager

Syntax

bool IsFlagSet(int Flag);

Description

Returns true if the dtxxxx document template constant specified in Flag is set.


See Also

dt Document View Constants


TDocManager::MatchTemplate

See Also	TDocManager

Syntax

TDocTemplate* MatchTemplate(const char far* path);

Description

Returns the first registered template whose pattern matches the given file name. If no template is compatible with the supplied file name, or if the template is open already, it returns 0.


See Also

TDocTemplate


TDocManager::PostDocError

See Also	TDocManager

Syntax

virtual uint PostDocError(TDocument& doc, uint sid, uint choice = MB_OK);

Description

Displays a message box with the error message passed as a string resource ID in sid. By default, the message box contains either an OK push button or a question mark icon. If an error message can't be found, PostDocError displays a "Message not found" message. choice can be one or more of the MB_Xxxx message  style constants. This function can be overridden.


See Also

TDocument::PostError

MB_Xxxx Message Constants


TDocManager::PostEvent

See Also	TDocManager

Syntax 1

virtual void PostEvent(int id, TDocument& doc);

Description

If the current document changes, posts a WM_OWLDOCUMENT message to indicate a change in the status of the document.

Syntax 2

virtual void PostEvent(int id, TView& view);

Description

If the current view changes, posts a WM_OWLVIEW message to indicate a change in the status of the view.


See Also

TDocument

TView


TDocManager::RefTemplate

See Also	TDocManager

Syntax

void RefTemplate(TDocTemplate&);

Description

Adds a template to the list of templates attached to the document.


See Also

TDocManager::UnRefTemplate

TDocTemplate


TDocManager::SelectAnySave

See Also	TDocManager

Syntax

virtual TDocTemplate* SelectAnySave(TDocument& doc, bool samedoc = true);

Description

Selects a registered template to save with this document.


See Also

TDocTemplate

TDocument


TDocManager::SelectSave

See Also	TDocManager

Syntax

bool SelectSave(TDocument& doc);

Description

Prompts the user to select a file name for the document. Filters out read-only files.


See Also

TDocTemplate::SelectSave


TDocManager::UnRefTemplate

See Also	TDocManager

Syntax

void UnRefTemplate(TDocTemplate&);

Description

Removes a template from the list of templates attached to the document.


See Also

TDocManager::RefTemplate

TDocTemplate


TDocManager::SelectDocPath

See Also	TDocManager

Syntax

virtual int SelectDocPath(TDocTemplate** tpllist, int tplcount, char far* path, int buflen, long flags, bool save=false);

Description

Prompts the user to select one of the templates to use for the file to be opened. Returns the template index used for the selection, or 0 if unsuccessful. For a file open operation, save is false. For a file save operation, save is true. This function can be overridden to provide a customized user interface.


See Also

TDocTemplate


TDocManager::SelectDocType

See Also	TDocManager

Syntax

virtual int SelectDocType(TDocTemplate** tpllist, int tplcount);

Description

Lets the user select a document type from a list of document templates. Returns the template index used for the selection, or 0 if unsuccessful. SelectDocType can be overridden, l


See Also

TDocTemplate


TDocManager::SelectViewType

See Also	TDocManager

Syntax

virtual int SelectViewType(TDocTemplate** tpllist, int tplcount);

Description

Lets the user select a view name for a new view from a list of view names. Returns the template index used for the selection or 0 if unsuccessful. SelectViewType can be overridden,


See Also

TDocTemplate


TDocManager Response Table Entries

TDocManager

Response table entry	Member function

EV_COMMAND(CM_FILECLOSE, CmFileClose)	CmFileClose

EV_COMMAND(CM_FILENEW, CmFileNew)	CmFileNew

EV_COMMAND(CM_FILEOPEN, CmFileOpen)	CmFileOpen

EV_COMMAND(CM_FILEREVERT, CmFileRevert)	CmFileRevert

EV_COMMAND(CM_FILESAVE, CmFileSave)	CmFileSave

EV_COMMAND(CM_FILESAVEAS, CmFileSaveAs)	CmFileSaveAs

EV_COMMAND(CM_VIEWCREATE, CmViewCreate)	CmViewCreate

EV_COMMAND_ENABLE(CM_FILECLOSE, CmEnableClose)	CmEnableClose

EV_COMMAND_ENABLE(CM_FILENEW, CmEnableNew)	CmEnableNew

EV_COMMAND_ENABLE(CM_FILEOPEN, CmEnableOpen)	CmEnableOpen

EV_COMMAND_ENABLE(CM_FILEREVERT, CmEnableRevert)	EmEnableRevert

EV_COMMAND_ENABLE(CM_FILESAVE, CmEnableSave)	CmEnableSave

EV_COMMAND_ENABLE(CM_FILESAVEAS, CmEnableSaveAs)	CmEnableSaveAs

EV_COMMAND_ENABLE(CM_VIEWCREATE, CmEnableCreate)	CmEnableCreate

EV_WM_CANCLOSE	EvCanClose

EV_WM_PREPROCMENU	EvPreProcessMenu

EV_WM_WAKEUP	EvWakeUp


TDocTemplate Class

OWL Hierarchy	Inheritance

Header File

doctpl.h

Description

TDocTemplate is an abstract base class that contains document template functionality. This document template class defines several functions that make it easier for you to use documents and their corresponding views. TDocTemplate classes create documents and views from resources and handle document naming and browsing. The document manager maintains a list of the current template objects. Each document type requires a separate document template.

Public Member Functions

void ClearFlag(long flag);

virtual TDocTemplate* Clone(TModule* module, TDocTemplate*& phead=TDocTemplateStaticHead)=0;

virtual TDocument* ConstructDoc(TDocument* parent = 0) = 0;

virtual TView* ConstructView(TDocument& doc = 0) = 0;

virtual TDocument* CreateDoc(const char far* path, long flags = 0)= 0;

virtual TView* CreateView(TDocument& doc, long flags) = 0;

const char far* GetDefaultExt() const;

const char far* GetDescription() const;

const char far* GetDirectory() const;

TDocManager* GetDocManager() const;

const char far* GetFileFilter() const;

long GetFlags() const;

TModule*& GetModule();

TDocTemplate* GetNextTemplate() const;

TRegList& GetRegList() const;

virtual const char far* GetViewName() = 0;

TDocument* InitDoc(TDocument* doc, const char far* path, long flags);

TView* InitView(TView* view);

bool IsFlagSet(long flag);

virtual TDocument* IsMyKindOfDoc(TDocument& doc)=0;

virtual TView* IsMyKindOfView(TView& view)=0;

bool IsStatic();

bool IsVisible();

bool SelectSave(TDocument& doc);

void SetDefaultExt(const char far*);

void SetDirectory(const char far*);

void SetDirectory(const char far*, int len);

void SetDocManager(TDocManager* dm);

void SetFileFilter(const char far*);

void SetFlag(long flag);

void SetModule(TModule* module);

Protected Constructor and Destructor

TDocTemplate(TRegList& regList, TModule*& module, TDocTemplate*& phead):

~TDocTemplate();


TDocTemplate::ClearFlag

See Also	TDocTemplate

Syntax

void ClearFlag(long flag);

Description

Clears a document template constant.


See Also

dt document template constants


TDocTemplate::Clone

TDocTemplate

Syntax

virtual TDocTemplate* Clone(TModule* module, TDocTemplate*& phead=DocTemplateStaticHead)=0;

Description

Makes a copy of a document template.


TDocTemplate::ConstructDoc

See Also	TDocTemplate

Syntax

virtual TDocument* ConstructDoc(TDocument* parent = 0) = 0;

Description

A pure virtual function that must be defined in a derived class, ConstructDoc creates a document specified by the document template class. Use this function in place of CreateDoc.


See Also

TDocManager::CreateDoc


TDocTemplate::ConstructView

See Also	TDocTemplate

Syntax

virtual TView* ConstructView(TDocument& doc = 0) = 0;

Description

A pure virtual function that must be defined in a derived class, ConstructView creates the view specified by the document template class.


See Also

TDocManager::CreateView


TDocTemplate::CreateDoc

See Also	TDocTemplate

Syntax

virtual TDocument* CreateDoc(const char far* path, long flags = 0)= 0;

Description

An obsolete pure virtual function that must be defined in a derived class, CreateDoc creates a document based on the directory path (path) and the specified template and flags value. If the path is 0 and the new flag (dtNewDoc) is not set, the dialog box is displayed. This function is obsolete: use ConstructDoc instead.


See Also

TDocManager::CreateAnyDoc

TDocTemplate::ConstructDoc


TDocTemplate::CreateView

See Also	TDocTemplate

Syntax

virtual TView* CreateView(TDocument& doc, long flags) = 0;

Description

A pure virtual function that must be defined in a derived class, CreateView creates the view specified by the document template class. This function is obsolete: use ConstructView instead.


See Also

TDocManager::CreateAnyView

TDocTemplate::ConstructView


TDocTemplate::GetDefaultExt

TDocTemplate

Syntax

const char far* GetDefaultExt() const;

Description

Gets the default extension to use if the user has entered the name of a file without any extension. If there is no default extension, GetDefaultExt contains 0.


TDocTemplate::GetDescription

TDocTemplate

Syntax

const char far* GetDescription() const;

Description

Gets the template description to put in the file-selection list box or the File|New menu-selection list box.


TDocTemplate::GetDirectory

See Also	TDocTemplate

Syntax

const char far* GetDirectory() const;

Description

Gets the directory path to use when searching for matching files. This will get updated if a file is selected and the dtUpdateDir flag is set.


See Also

dt document template constants


TDocTemplate::GetDocManager

TDocTemplate

Syntax

TDocManager* GetDocManager() const;

Description

Points to the document manager.


TDocTemplate::GetFileFilter

TDocTemplate

Syntax

const char far* GetFileFilter() const;

Description

Gets any valid document matching pattern to use when searching for files.


TDocTemplate::GetFlags

See Also	TDocTemplate

Syntax

long GetFlags() const;

Description

Gets the document template constants, which indicate how the document is created and opened.


See Also

dt xxxx document template constants


TDocTemplate::GetModule

TDocTemplate

Syntax

TModule*& GetModule();

Description

Returns a module pointer.


TDocTemplate::GetNextTemplate

TDocTemplate

Syntax

TDocTemplate* GetNextTemplate() const;

Description

Gets the next template in the list of templates.


TDocTemplate::GetRegList

TDocTemplate

Syntax

TRegList& GetRegList() const;

Description

Gets the program's registration table, which contains the program's current program ID, class ID, executable path, as well as other attributes used to construct a  TDocTemplate  object. See the entry for Registration macros in this manual for information about how the registration macros generate registration information.


TDocTemplate::GetViewName

TDocTemplate

Syntax

virtual const char far* GetViewName() = 0;

Description

A pure virtual function that must be defined in a derived class, GetViewName gets the name of the view associated with the template.


TDocTemplate::IsFlagSet

See Also	TDocTemplate

Syntax

bool IsFlagSet(long flag);

Description

Returns nonzero if the document template flag is set.


See Also

dt xxxx document template constants


TDocTemplate::IsMyKindOfDoc

See Also	TDocTemplate

Syntax

virtual TDocument* IsMyKindOfDoc(TDocument& doc)=0;

Description

A pure virtual function that must be defined in a derived class, IsMyKindOfDoc tests if the template belongs to the same class as the document or to a derived class.


See Also

TDocTemplateT::IsMyKindOfDoc


TDocTemplate::IsMyKIndofView

TDocTemplate

Syntax

virtual TView* IsMyKindOfView(TView& view) = 0;

Description

A pure virtual function that must be defined in a derived class, IsMyKindofView tests if the template belongs to the same class as the view or to a derived class.


TDocTemplate::IsStatic

TDocTemplate

Syntax

bool IsStatic();

Description

Returns true fi the template is statically constructed.


TDocTemplate::IsVisible

TDocTemplate

Syntax

bool IsVisible();

Description

Indicates whether the document can be displayed in the file selection dialog box. A document is visible if dtHidden isn't set and Description isn't 0.


TDocTemplate::SelectSave

TDocTemplate

Syntax

bool SelectSave(TDocument& doc);

Description

Prompts the user to select a file name for the document. Filters out read-only files.


TDocTemplate::SetDefaultExt

TDocTemplate

Syntax

void SetDefaultExt(const char far*);

Description

Sets the default extension to use if the user has entered the name of a file without any extension. If there is no default extension, SetDefaultExt contains 0.


TDocTemplate::SetDirectory

See Also	TDocTemplate

Form 1

void SetDirectory(const char far*);

Form 2

void SetDirectory(const char far*, int len);

Description

Sets the directory path to use when searching for matching files. This will get updated if a file is selected and the dtUpdateDir flag is set.


See Also

TDocTemplate::GetDirectory


TDocTemplate::SetDocManager

TDocTemplate

Syntax

void SetDocManager(TDocManager* dm);

Description

Sets the current document manager to the argument dm.


TDocTemplate::SetFileFilter

TDocTemplate

Syntax

void SetFileFilter(const char far*);

Description

Sets the valid document matching pattern to use when searching for files.


TDocTemplate::SetFlag

See Also	TDocTemplate

Syntax

void SetFlag(long flag);

Description

Sets the document template constants, which indicate how the document is created and opened.


See Also

dtxxxx document template constants


TDocTemplate::SetModule

TDocTemplate

Syntax

TModule*& SetModule();

Description

Sets a module pointer.


TDocTemplate Protected Constructor and Destructor

See AlsoTDocTemplate_Protectedconstructorsanddestructor	TDocTemplate

Constructor

TDocTemplate(TRegList& regList, TModule*& module, TDocTemplate*& phead):

Destructor

~TDocTemplate();

Description

 Uses the information in the registration table (regList) to construct a TDocTemplate with the specified file description, file filter pattern, search path for viewing the directory, default file extension, and flags representing the view and creation options from the registration list.  Then, adds this template to the document manager's template list. If the document manager is not yet constructed, adds the template to a static list, which the document manager will later add to its template list.

The argument, module, specifies the TModule of the caller. phead specifies the template head for the caller's module. See the Registration macros entry in this manual for information about the registration macros that generate a  TRegList  , which contains the attributes used to create a  TDocTemplate  object.

Destructor

Destroys a TDocTemplate object and frees the data members (FileFilter, Description, Directory, and DefaultExt). The Destructor is called only when no views or documents are associated with the template. Instead of calling this Destructor directly, use the Delete member function.


See Also

dt xxxx document template constants


TDocTemplate::InitDoc

See Also	TDocTemplate

Syntax

TDocument* InitDoc(TDocument* doc, const char far* path, long flags);

Description

InitDoc is called only from the subclass so that CreateDoc can continue its document processing.


See Also

TDocTemplate::CreateDoc


TDocTemplate::InitView

See Also	TDocTemplate

Syntax

TView* InitView(TView* view);

Description

Called only from the subclass to continue CreateView processing.


See Also

TDocTemplate::CreateView


TDocTemplateT<D,V> Class

Header

doctpl.h

Description

To register the associated document and view classes, a parameterized subclass, TDocTemplateT<D,V>, is used to construct a particular document and view, where D represents the document class and V represents the view class. The parameterized template classes are created using a macro, which also generates the associated streamable support. The document and view classes are provided through the use of a parameterized subclass. The template class name is used as a typedef for the parameterized class. For example,

DEFINE_DOC_TEMPLATE_CLASS(TFileDocument, TEditView, MyEditFile)

You can instantiate a document template using either a static member or an explicit construction. For example,

MyEditFile et1("Edit text files",

      "*.txt","D:\\doc",".TXT"",dtNoAutoView);

new MyEditFile(.....)

When a document template is created, the document manager (TDocManager) registers the template. When the document template's delete function is called to delete the template, it is no longer visible to the user. However, it remains in memory as long as any documents still use it.

Public Constructors

TDocTemplateT(const char far* filt, const char far* desc, const char far* dir, const char far* ext, long flags = 0, TModule*& module = ::Module, TDocTemplate*& phead = DocTemplateStaticHead);

TDocTemplateT(TRegList& regList, TModule*& module = ::Module, TDocTemplate*& phead = DocTemplateStaticHead);

Public Member Functions

TDocTemplateT* Clone(TModule* module, TDocTemplate*& phead = DocTemplateStaticHead);

D* CreateDoc(const char far* path, long flags = 0);

TView* CreateView(TDocument& doc, long flags = 0);

D* IsMyKindOfDoc(TDocument& doc);

V* IsMyKindOfView(TView& view);

virtual const char far* GetViewName();


TDocTemplateT Public Constructor
TDocTemplateT Public Constructors

TDocTemplate::TDocTemplateT

Syntax 1

TDocTemplateT(const char far* filt, const char far* desc, const char far* dir, const char far* ext, long flags = 0, TModule*& module = ::Module, TDocTemplate*& phead = DocTemplateStaticHead);

Description

Constructs a TDocTemplateT with the specified file description (desc), file filter pattern (filt), search path for viewing the directory (dir), default file extension (ext), and flags representing the view and creation options (flags). module, which is instantiated and exported directly from every executable module, can be used to access the current instance.

Syntax 2

TDocTemplateT(TRegList& regList, TModule*& module = ::Module, TDocTemplate*& phead = DocTemplateStaticHead);

Description

Constructs a TDocTemplateT  using the registration table to determine the file filter pattern, search path for viewing the directory, default file extension, and flag values. See the entry in this manual for registration macros for more information about how the registration tables are created. module, which is instantiated and exported directly from every executable module, can be used to access the current instance.


TDocTemplateT::Clone

TDocTemplate::TDocTemplateT

Syntax

TDocTemplateT* Clone(TModule* module, TDocTemplate*& phead = DocTemplateStaticHead;

Description

Makes a copy of the TDocTemplateT object.


TDocTemplateT::CreateDoc

See Also	TDocTemplate::TDocTemplateT

Syntax

D* CreateDoc(const char far* path, long flags = 0);

Description

Creates a document of type D based on the directory path (path) and flags value.


See Also

TDocTemplate::CreateDoc


TDocTemplateT::CreateView

See Also	TDocTemplate::TDocTemplateT

Syntax

TView* CreateView(TDocument& doc, long flags = 0);

Description

Creates the view specified by the document template class.


See Also

TDocManager::CreateAnyView


TDocTemplateT::IsMyKindOfDoc

See Also	TDocTemplate::TDocTemplateT

Syntax

D* IsMyKindOfDoc(TDocument& doc);

Description

Tests to see if the document (doc) is either the same class as the template's document class or a derived class. If the template can't use the document, IsMyKIndOfDoc returns 0.


See Also

TDocTemplate::IsMyKindOfDoc


TDocTemplateT::IsMyKindOfView

TDocTemplate::TDocTemplateT

Syntax

V* IsMyKindOfView(TView& view);

Description

Tests to see if the view (view) is either the same class as the template's view class or a derived class. If the template can't use the view, IsMyKIndOfView returns 0.


TDocTemplateT::GetViewName

TDocTemplate::TDocTemplateT

Syntax

virtual const char far* GetViewName();

Description

Gets the name of the view associated with the template.


TDropInfo Class

OWL Hierarchy

Header File

geometry.h

Description

TDropInfo is a simple class that supports file-name drag and drop operations using the WM_DROPFILES message. Each TDropInfo object has a private handle to the HDROP structure returned by the WM_DOPFILES message.

Public Constructor

TDropInfo(HDROP handle);

Public Member Functions

void DragFinish();

uint DragQueryFile( uint index, char far* name, uint nameLen)

uint DragQueryFileCount();

uint DragQueryFileNameLen(uint index)

bool DragQueryPoint(TPoint& point)

operator HDROP();


TDropInfo Public Constructor

TDropInfo

Syntax

TDropInfo(HDROP handle);

Description

Creates a TDropInfo object with Handle set to the given handle.


TDropInfo::DragFinish

TDropInfo

Syntax

void DragFinish();

Description

Releases any memory allocated for the transferring of this TDropInfo object's files during drag operations.


TDropInfo::DragQueryFile

See Also	TDropInfo

Syntax

uint DragQueryFile( uint index, char far* name, uint nameLen)

Description

Retrieves the name of the file and related information for this i object. If index is set to -1 (0xFFFF), DragQueryFile returns the number of dropped files. This is equivalent to calling DragQueryFileCount.

If index lies between 0 and the total number of dropped files for this object, DragQueryFile copies to the name buffer (of length nameLen bytes) the name of the dropped file that corresponds to index, and returns the number of bytes actually copied.

If name is 0, DragQueryFile returns the required buffer size (in bytes) for the given index. This is equivalent to calling DragQueryFileNameLen.


See Also

TDropInfo::DragQueryPoint

TDropInfo::DragQueryFileCount


TDropInfo::DragQueryFileCount

See Also	TDropInfo

Syntax

uint DragQueryFileCount();

Description

Returns the number of dropped files in this TDropInfo object. This call is equivalent to calling DragQueryFile(-1, 0, 0).


See Also

TDropInfo::DragQueryFile


TDropInfo::DragQueryFileNameLen

See Also	TDropInfo

Syntax

uint DragQueryFileNameLen(uint index)

Description

Returns the length of the name of the file in this TDropInfo object corresponding to the given index. This call is equivalent to calling DragQueryFile(index, 0, 0).


See Also

TDropInfo::DragQueryFile


TDropInfo::DragQueryPoint

See Also	TDropInfo

Syntax

bool DragQueryPoint(TPoint& point)

Description

Retrieves the mouse pointer position when this object's files are dropped and copies the coordinates to the given point object. point refers to the window that received the WM_DROPFILES message. DragQueryPoint returns true if the drop occurs inside the window's client area, otherwise false.


See Also

TPoint


TDropInfo::operator HDROP()

TDropInfo

Syntax

operator HDROP();

Description

Typecasting operator that returns Handle.


TEdgeConstraint struct

See Also	OWL Hierarchy

Header File

layoutco.h

Description

TEdgeConstraint adds member functions that set edge (but not size) constraints. TEdgeConstraint always places your window one pixel above the other window and then adds margins.

For example, if the margin is 4, TEdgeConstraint places your window 5 pixels above the other window. The margin, which does not need to be measured in pixels, is defined using the units specified by the constraint. Therefore, if the margin is specified as 8 layout units (which are then converted to 12 pixels), your window would be placed 13 pixels above the other window.

Public Member Functions

void Above (TWindow *sibling, int margin = 0)

void Absolute (TEdge edge, int value)

void Below(TWindow *sibling, int margin = 0);

void LeftOf (TWindow *sibling, int margin = 0)

void PercentOf (TWindow *otherWin, TEdge edge, int percent)

void RightOf (TWindow *sibling, int margin = 0)

void SameAs (TWindow *otherWin, TEdge edge)

void Set(TEdge edge, TRelationship rel, TWindow *otherWin, TEdge otherEdge, int value = 0);


See Also

TLayoutConstraint struct

TEdgeOrSizeConstraint struct

TLayoutWindow  (layout constraints example)


TEdgeConstraint Above
TEdgeConstraint::Above

See Also	TEdgeConstraints

Syntax

void Above (TWindow *sibling, int margin = 0)

Description

Positions your window above a sibling window. You must specify the sibling window and an optional margin between the two windows. If no margin is specified, Above sets the bottom of one window one pixel above the top of the other window.


See Also

TEdgeConstraint::Below


TEdgeConstraint::Absolute

See Also	TEdgeConstraints

Syntax

void Absolute (TEdge edge, int value)

Description

Sets an edge of your window to a fixed value.


See Also

TEdgeConstraint::PercentOf

TEdgeOrSizeConstraint::Absolute


TEdgeConstraint::Below

See Also	TEdgeConstraints

Syntax

void Below(TWindow *sibling, int margin = 0);

Description

Positions your window with respect to a sibling window. You must specify the sibling window and an optional margin between the two windows. If no margin is specified, Below sets the top of one window one pixel below the bottom of the other window.


See Also

TEdgeConstraint::Above


TEdgeConstraint::LeftOf

See Also	TEdgeConstraints

Syntax

void LeftOf (TWindow *sibling, int margin = 0)

Description

Positions one window with respect to a sibling window. You can specify the sibling window and an optional margin between the two windows.


See Also

TEdgeConstraint::RightOf


TEdgeConstraint::PercentOf

See Also	TEdgeConstraints

Syntax

void PercentOf (TWindow *otherWin, TEdge edge, int percent)

Description

Specifies that the edge of one window indicated in edge should be a percentage of the corresponding edge of another window  (otherWin.


See Also

TEdgeConstraint::Absolute

TEdgeOrSizeConstraint::PercentOf


TEdgeConstraint::RightOf

See Also	TEdgeConstraints

Syntax

void RightOf (TWindow *sibling, int margin = 0)

Description

Positions one window with respect to a sibling window. You can specify the sibling window and an optional margin between the two windows.


See Also

TEdgeConstraint::LeftOf


TEdgeConstraint::SameAs

See Also	TEdgeConstraints

Syntax

void SameAs (TWindow *otherWin, TEdge edge)

Description

Sets the edge of your window indicated by edge equivalent to the corresponding edge of the window in otherWin.


See Also

TEdgeConstraint::Set

TEdgeOrSizeConstraint::SameAs


TEdgeConstraint::Set

See Also	TEdgeConstraints

Syntax

void Set(TEdge edge, TRelationship rel, TWindow *otherWin, TEdge otherEdge, int value = 0);

Description

Used for setting arbitrary edge constraints, Set specifies that your window's edge should be of a specified relationship to otherWin's specified edge.


See Also

TEdgeConstraint::SameAs


TEdgeConstraint::TEdgeOrSizeConstraint struct
TEdgeOrSizeConstraint struct

TEdgeConstraints

Header File

layoutco.h

Description

Derived from TEdgeConstraint, TEdgeOrSizeConstraint is a template class that supports size constraints in addition to all the operations that TEdgeConstraint provides. The width or height is specified in the template instantiation of this class. There are two versions of each member function: one sets both edge and size constraints; the other sets only edge constraints.

Public Member Functions

void Absolute (int value)

void Absolute (TEdge edge, int value)

void PercentOf (TWindow *otherWin, int percent, TWidthHeight otherWidthHeight = widthOrHeight)

void PercentOf (TWindow *otherWin, TEdge edge, int percent)

void SameAs (TWindow *otherWin, TWidthHeight otherWidthHeight = widthOrHeight, int value = 0)

void SameAs (TWindow *otherWin, TEdge edge)


TEdgeOrSizeConstraint::Absolute

TEdgeConstraints

Form 1

void Absolute (int value)

Form 2

void Absolute (TEdge edge, int value)

Description

Form 1: Sets the width or height of your window to a fixed value.

Form 2: Used to determine edge constraints only, Absolute sets the edge of your window to a fixed value.


See Also

TEdgeConstraint::Absolute


TEdgeOrSizeConstraint::PercentOf

See Also	TEdgeConstraints

Form 1

void PercentOf (TWindow *otherWin, int percent, TWidthHeight otherWidthHeight = widthOrHeight)

Form 2

void PercentOf (TWindow *otherWin, TEdge edge, int percent)

Description

Form 1: Although a window's width or height defaults to being a percentage of the sibling or parent window's corresponding dimension, it can also be a percentage of the sibling or parent's opposite dimension. For example, one window's width can be 50% of the parent window's height.

Form 2: Used to determine edge constraints only, PercentOf specifies that the edge of one window indicated in edge should be a percentage of the corresponding edge of another window  (otherWin.


See Also

TEdgeOrSizeConstraint::Absolute

TEdgeConstraint::PercentOf


TEdgeOrSizeConstraint::SameAs

See Also	TEdgeConstraints

Form 1

void SameAs (TWindow *otherWin, TWidthHeight otherWidthHeight = widthOrHeight, int value = 0)

Form 2

void SameAs (TWindow *otherWin, TEdge edge)

Description

Form 1: Although a window's width or height defaults to being the same as the sibling or parent window's corresponding dimension, it can be the same of the sibling's or parent's opposite dimension. For example, one window's width can be the same as the parent window's height.

Form 2: Used to determine edge constraints only, SameAs sets the edge of one window the same as the corresponding edge of the other window specified in otherWin.


See Also

TEdgeOrSizeConstraint::PercentOf

TEdgeConstraint::SameAs


TEdit Class

OWL Hierarchy	Inheritance

Header File

edit.h

Description

A TEdit is an interface object that represents an edit control interface element. A TEdit object must be used to create an edit control in a parent TWindow. A TEdit can be used to facilitate communication between your application and the edit controls of a TDialog. This class is streamable.

There are two styles of edit control objects: single line and multiline. Multiline edit controls allow editing of multiple lines of text.

The position of the first character in an edit control is zero. For a multiline edit control, the position numbers continue sequentially from line to line; line breaks count as two characters.

Most of TEdit's member functions manage the edit control's text. TEdit also includes some automatic member response functions that respond to selections from the edit control's parent window menu, including cut, copy, and paste. Two important member functions inherited from TEdit's base class (TStatic) are GetText and SetText.

Public Constructors

TEdit(TWindow* parent, int Id, const char far *text, int x, int y, int w, int h, uint textLen = 0, bool multiline = false, TModule* module = 0);

TEdit(TWindow* parent, int resourceID, uint textLen = 0, TModule* module = 0);

Public Member Functions

bool CanUndo();

void Clear();

void ClearModify();

void Copy();

void Cut();

bool DeleteLine(int lineNumber);

bool DeleteSelection();

bool DeleteSubText(uint startPos, uint endPos);

void EmptyUndoBuffer();

void FormatLines(bool addEOL);

int GetFirstVisibleLine() const;

HLOCAL GetHandle() const;

bool GetLine(char far* str, int strSize, int lineNumber);

int GetLineFromPos(uint charPos);

uint GetLineIndex(int lineNumber);

int GetLineLength(int lineNumber);

int GetNumLines();

uint GetPasswordChar() const;

void GetRect(TRect& frmtRect) const;

void GetSelection(uint& startPos, uint& endPos);

void GetSubText(char far* str, uint startPos, uint endPos);

EDITWORDBREAKPROC GetWordBreakProc() const;

void Insert(const char far* str);

bool IsModified();

bool IsValid(bool reportErr = false);

char far* LockBuffer(uint newsize=0);

void Paste();

void Scroll(int horizontalUnit, int verticalUnit);

int Search(uint startPos, const char far* text, bool caseSensitive=false, bool wholeWord=false, bool up=false);

void SetHandle(HLOCAL localMem);

void SetPasswordChar(uint ch);

void SetReadOnly(bool readOnly);

void SetRect(const TRect& frmtRect);

void SetRectNP(const TRect& frmtRect);

bool SetSelection(uint startPos, uint endPos);

void SetTabStops(int numTabs, const int far* tabs);

void SetValidator(TValidator* validator);

void SetWordBreakProc(EDITWORDBREAKPROC proc);

uint Transfer(void* buffer TTransferDirection direction);

void Undo();

void UnlockBuffer(const char far* buffer, bool updateHandle=false);

void ValidatorError();

Protected Data Member

TValidator* Validator;

Protected Member Functions

bool CanClose();

void CmCharsEnable(TCommandEnabler& commandHandler);

void CmEditClear();

void CmEditCopy();

void CmEditCut();

void CmEditDelete();

void CmEditPaste();

void CmEditUndo();

void CmModEnable(TCommandEnabler& commandHandler);

void CmPasteEnable(TCommandEnabler& commandHandler);

void CmSelectEnable(TCommandEnabler& commandHandler);

void ENErrSpace();

void EvChar(uint key, uint repeatCount, uint flags);

uint EvGetDlgCode(MSG far* msg);

void EvKeyDown(uint key, uint repeatCount, uint flags);

void EvKillFocus(HWND hWndGetFocus);

char far* GetClassName();

void SetupWindow();

Response Table Entries

EV_ macros and member functions


TEdit Public Constructors

See Also	TEdit

Form 1

TEdit(TWindow* parent, int Id, const char far *text, int x, int y, int w, int h, uint textLen = 0, bool multiline = false, TModule* module = 0);

Form 2

TEdit(TWindow* parent, int resourceID, uint textLen = 0, TModule* module = 0);

Description

Form 1: Constructs an edit control object with a parent window (parent). Sets the creation attributes of the edit control and fills its Attr data members with the specified control ID (Id), position (x, y) relative to the origin of the parent window's client area, width (w), and height (h).

If text buffer length (textLen) is 0 or 1, there is no explicit limit to the number of characters that can be entered. Otherwise textLen - 1 characters can be entered. By default, initial text (text) in the edit control is left-justified and the edit control has a border. Multiline edit controls have horizontal and vertical scroll bars.

Form 2: Constructs a TEdit object to be associated with an edit control of a TDialog. Invokes the TStatic constructor with identical parameters. The resourceID parameter must correspond to an edit resource that you define. Enables the data transfer mechanism by calling EnableTransfer.


See Also

TStatic::TStatic


TEdit::CanUndo

See Also	TEdit

Syntax

bool CanUndo();

Description

Returns true if it is possible to undo the last edit.


See Also

TEdit::Undo


TEdit::Clear

TEdit

Syntax

void Clear();

Description

Overrides TStatic's virtual member function and clears all text.


TEdit::ClearModify

See Also	TEdit

Syntax

void ClearModify();

Description

Resets the change flag of the edit control causing IsModified to return false. The flag is set when text is modified.


See Also

TEdit::IsModified


TEdit::Copy

TEdit

Syntax

void Copy();

Description

Copies the currently selected text into the Clipboard.


TEdit::Cut

TEdit

Syntax

void Cut();

Description

Deletes the currently selected text and copies it into the Clipboard.


TEdit::DeleteLine

TEdit

Syntax

bool DeleteLine(int lineNumber);

Description

Deletes the text in the line specified by lineNumber in a multiline edit control. If -1 passed, deletes the current line. DeleteLine does not delete the line break and affects no other lines. Returns true if successful. Returns false if lineNumber is not -1 and is out of range or if an error occurs.


TEdit::DeleteSelection

TEdit

Syntax

bool DeleteSelection();

Description

Deletes the currently selected text, and returns false if no text is selected.


TEdit::DeleteSubText

TEdit

Syntax

bool DeleteSubText(uint startPos, uint endPos);

Description

Deletes the text between the starting and ending positions specified by startPos and endPos, respectively. DeleteSubText returns true if successful.


TEdit::EmptyUndoBuffer

TEdit

Syntax

void EmptyUndoBuffer();

Description

If an operation inside the edit control can be undone, the edit control undo flag is set. EmptyUndoBuffer resets or clears this flag.


TEdit::FormatLines

TEdit

Syntax

void FormatLines(bool addEOL);

Description

Indicates if the end-of-line characters (carriage return, linefeed) are to be added or removed from text lines that are wordwrapped in a multiline edit control. Returns true if these characters are placed at the end of wordwrapped lines or false if they are removed.


TEdit::GetFirstVisibleLine

TEdit

Syntax

int GetFirstVisibleLine() const;

Description

Indicates the topmost visible line in an edit control. For single-line edit controls, the return value is 0. For multiline edit controls, the return value is the index of the topmost visible line.


TEdit::GetHandle

See Also	TEdit

Syntax

HLOCAL GetHandle() const;

Description

Returns the data handle of the buffer that holds the contents of the control window.

This function is obsolete, and is not available under Presentation Manager.


See Also

TEdit::SetHandle


TEdit::GetLine

See Also	TEdit

Syntax

bool GetLine(char far* str, int strSize, int lineNumber);

Description

Retrieves a line of text (whose line number is supplied) from the edit control and returns it in str (NULL-terminated). strSize indicates how many characters to retrieve. GetLine returns false if it is unable to retrieve the text or if the supplied buffer is too small.


See Also

TStatic::GetText

TEdit::GetNumLines

TEdit::GetLineLength


TEdit::GetLineFromPos

TEdit

Syntax

int GetLineFromPos(uint charPos);

Description

From a multiline edit control, returns the line number on which the character position specified by charPos occurs. If charPos is greater than the position of the last character, the number of the last line is returned. If charPos is-1, the number of the line that contains the first selected character is returned. If there is no selection, the line containing the caret is returned.


TEdit::GetLineIndex

TEdit

Syntax

uint GetLineIndex(int lineNumber);

Description

In a multiline edit control, GetLineIndex returns the number of characters that appear before the line number specified by lineNumber. If lineNumber is -1, GetLineIndex returns the number of the line that contains the caret is returned.


TEdit::GetLineLength

TEdit

Syntax

int GetLineLength(int lineNumber);

Description

From a multiline edit control, GetLineLength returns the number of characters in the line specified by lineNumber. If it is -1, the following applies: if no text is selected, GetLineLength returns the length of the line where the caret is positioned; if text is selected on the line, GetLineLength returns the line length minus the number of selected characters; if selected text spans more than one line, GetLineLength returns the length of the lines minus the number of selected characters.


TEdit::GetNumLines

TEdit

Syntax

int GetNumLines();

Description

Returns the number of lines that have been entered in a multiline edit control: 1 if the edit control has no text (if it has one line with no text in it), or 0 if there is no text or if an error occurs.


TEdit::GetPasswordChar

See Also	TEdit

Syntax

uint GetPasswordChar() const;

Description

Returns the character to be displayed in place of a user-typed character. When the edit control is created with the ES_PASSWORD style specified, the default display character is an asterisk (*).


See Also

TEdit::SetPasswordChar


TEdit::GetRect

See Also	TEdit

Syntax

void GetRect(TRect& frmtRect) const;

Description

Gets the formatting rectangle of a multiline edit control.


See Also

TEdit::SetRect

TEdit::SetRectNP


TEdit::GetSelection

See Also	TEdit

Syntax

void GetSelection(uint& startPos, uint& endPos);

Description

Returns the starting (startPos) and ending (endPos) positions of the currently selected text. By using GetSelection in conjunction with GetSubText, you can get the currently selected text.


See Also

TEdit::GetSubText


TEdit::GetSubText

See Also	TEdit

Syntax

void GetSubText(char far* str, uint startPos, uint endPos);

Description

Retrieves the text in an edit control from indexes startPos to endPos and returns it in str.


See Also

TEdit::GetSelection


TEdit::GetWordBreakProc

See Also	TEdit

Syntax

EDITWORDBREAKPROC GetWordBreakProc() const;

Description

Retrieves the current wordwrap function. Returns the address of the wordwrap function defined by the application or 0 if none exists.


See Also

TEdit::SetWordBreakProc


TEdit::Insert

See Also	TEdit

Syntax

void Insert(const char far* str);

Description

Inserts the text supplied in str into the edit control at the current text insertion point (cursor position), and replaces any currently selected text. Insert is similar to Paste, but does not affect the Clipboard.


See Also

TEdit::Paste


TEdit::IsModified

See Also	TEdit

Syntax

bool IsModified();

Description

Returns true if the user has changed the text in the edit control.


See Also

TEdit::ClearModify


TEdit::IsValid

TEdit

Syntax

bool IsValid(bool reportErr = false);

Description

Returns true if the contents of the edit control are valid. reportErr is false so that, by default, IsValid doesn't bring up a system or custom message box with an error string created from the default string table.


TEdit::LockBuffer

See Also	TEdit

Syntax

char far* LockBuffer(uint newsize=0);

Description

Locks the edit control's buffer and returns a pointer to the buffer. Passing newsize greater than 0 causes the buffer to be resized to newsize. You must call Unlock when you are finished.


See Also

TEdit::UnLockBuffer


TEdit::Paste

See Also	TEdit

Syntax

void Paste();

Description

Inserts text from the Clipboard into the edit control at the current text insertion point (cursor position).


See Also

TEdit::CMEditPaste


TEdit::Scroll

TEdit

Syntax

void Scroll(int horizontalUnit, int verticalUnit);

Description

Scrolls a multiline edit control horizontally and vertically using the numbers of characters specified in horizontalUnit and verticalUnit. Positive values result in scrolling to the right or down in the edit control, and negative values result in scrolling to the left or up.


TEdit::Search

TEdit

Syntax

int Search(uint startPos, const char far* text, bool caseSensitive=false, bool wholeWord=false, bool up=false);

Description

Performs either a case-sensitive or case-insensitive search for the supplied text. If the text is found, the matching text is selected, and Search returns the position of the beginning of the matched text. If the text is not found in the edit control's text, Search returns -1. If -1 is passed as startPos, then the search starts from either the end or the beginning of the currently selected text, depending on the search direction.


TEdit::SetHandle

See Also	TEdit

Syntax

void SetHandle(HLOCAL localMem);

Description

Sets a handle to the text buffer used to hold the contents of a multiline edit control.

This function is obsolete, and is not available under Presentation Manager.


See Also

TEdit::GetHandle


TEdit::SetPasswordChar

See Also	TEdit

Syntax

void SetPasswordChar(uint ch);

Description

SetPasswordChar sets the character to be displayed in place of a user-typed character. When the ES_PASSWORD style is specified, the default display character is an asterisk (*).


See Also

TEdit::GetPasswordChar


TEdit::SetReadOnly

TEdit

Syntax

void SetReadOnly(bool readOnly);

Description

Sets the edit control to be read-only or read-write.


TEdit::SetRect

See Also	TEdit

Syntax

void SetRect(const TRect& frmtRect);

Description

Sets the formatting rectangle for a multiline edit control.


See Also

TEdit::GetRect

TEdit::SetRectNP


TEdit::SetRectNP

See Also	TEdit

Syntax

void SetRectNP(const TRect& frmtRect);

Description

Sets the formatting rectangle for a multiline edit control. Unlike SetRect, SetRectNP does not repaint the edit control.


See Also

TEdit::GetRect

TEdit::SetRect


TEdit::SetSelection

TEdit

Syntax

bool SetSelection(uint startPos, uint endPos);

Description

Forces the selection of the text between the positions specified by startPos and endPos, but not including the character at endPos.


TEdit::SetTabStops

TEdit

Syntax

void SetTabStops(int numTabs, const int far* tabs);

Description

Sets the tab stop positions in a multiline edit control.


TEdit::SetValidator

TEdit

Syntax

void SetValidator(TValidator* validator);

Description

Establishes the validator object for the edit control.


TEdit::SetWordBreakProc

See Also	TEdit

Syntax

void SetWordBreakProc(EDITWORDBREAKPROC proc);

Description

In a multiline edit control, SetWordBreakProc indicates that an application-supplied word-break function has replaced the default word-break function. The application-supplied word-break function might break the words in the text buffer at a character other than the default blank character.


See Also

TEdit::GetWordBreakProc


TEdit::Transfer

TEdit

Syntax

uint Transfer(void* buffer TTransferDirection direction);

Description

Transfers information for TEdit controls and sends information to the Validator if one exists, and if it has the transfer option set. Transfer can perform type conversion when validators are in place, for example, when TRangeValidator transfers integers. The return value is the size (in bytes) of the transfer data.


TEdit::Undo

See Also	TEdit

Syntax

void Undo();

Description

Undoes the last edit.


See Also

TEdit::CanUndo

TEdit::CMEditUndo


TEdit::UnlockBuffer

See Also	TEdit

Syntax

void UnlockBuffer(const char far* buffer, bool updateHandle=false);

Description

Unlocks a locked edit control buffer. If the contents were changed, updateHandle should be true.


See Also

TEdit::LockBuffer


TEdit::ValidatorError

TEdit

Syntax

void ValidatorError();

Description

Handles validation errors that occur as a result of validating the edit control.


TEdit::Validator

TEdit

Syntax

TValidator* Validator;

Description

Points to the validator object constructed in your derived class to validate input text. If no validator exists, Validator is zero.


TEdit::CanClose

TEdit

Syntax

bool CanClose();

Description

Checks to see if all child windows can be closed before closing the current window. If any child window returns false, CanClose returns false and terminates the process. If all child windows can be closed, CanClose returns true.


TEdit::CmCharsEnable

TEdit

Syntax

void CmCharsEnable(TCommandEnabler& commandHandler);

Description

Determines whether the Clear menu item is enabled for the currently selected text.


TEdit::CmEditClear

See Also	TEdit

Syntax

void CmEditClear();

Description

Automatically responds to a menu selection with a menu ID of CM_EDITCLEAR by calling Clear.


See Also

TStatic::Clear


TEdit::CmEditCopy

See Also	TEdit

Syntax

void CmEditCopy();

Description

Automatically responds to a menu selection with a menu ID of CM_EDITCOPY by calling Copy.


See Also

TEdit::Copy


TEdit::CmEditCut

See Also	TEdit

Syntax

void CmEditCut();

Description

Automatically responds to a menu selection with a menu ID of CM_EDITCUT by calling Cut.


See Also

TEdit::Cut


TEdit::CmEditDelete

See Also	TEdit

Syntax

void CmEditDelete();

Description

Automatically responds to a menu selection with a menu ID of CM_EDITDELETE by calling DeleteSelection.


See Also

TEdit::DeleteSelection


TEdit::CmEditPaste

See Also	TEdit

Syntax

void CmEditPaste();

Description

Automatically responds to a menu selection with a menu ID of CM_EDITPASTE by calling Paste.


See Also

TEdit::Paste


TEdit::CmEditUndo

See Also	TEdit

Syntax

void CmEditUndo();

Description

Automatically responds to a menu selection with a menu ID of CM_EDITUNDO by calling Undo.


See Also

TEdit::Undo


TEdit::CmModEnable

TEdit

Syntax

void CmModEnable(TCommandEnabler& commandHandler);

Description

Determines whether the Undo menu item is enabled for the selected text.


TEdit::CmPasteEnable

TEdit

Syntax

void CmPasteEnable(TCommandEnabler& commandHandler);

Description

Determines whether the Paste menu item is enabled for the selected text.


TEdit::CmSelectEnable

TEdit

Syntax

void CmSelectEnable(TCommandEnabler& commandHandler);

Description

Determines whether the Cut, Copy, or Delete menu items are enabled for the selected text.


TEdit::ENErrSpace

TEdit

Syntax

void ENErrSpace();

Description

Sounds a beep in response to an error notification message that is sent when the edit control unsuccessfully attempts to allocate more memory.


TEdit::EvChar

TEdit

Syntax

void EvChar(uint key, uint repeatCount, uint flags);

Description

Validates the text entered into the edit control. If the input is incorrect, the original text is restored. Otherwise, the validated and modified text is placed back into the edit control, so the results of the auto-fill (if any) can be viewed. When IsValidInput is called, the SupressFill parameter defaults to False, so that the string can be modified.


TEdit::EvKeyDown

TEdit

Syntax

void EvKeyDown(uint key, uint repeatCount, uint flags);

Description

EvKeyDown translates the virtual key code into a movement. key indicates the virtual key code of the pressed key, repeatCount holds the number of times the same key is pressed, flags contains one of the messages that translates to a virtual key (VK) code for the mode indicators. If the Tab key is sent to the Edit Control, EvKeyDown checks the validity before allowing the focus to change.


TEdit::EvGetDlgCode

See Also	TEdit

Syntax

uint EvGetDlgCode(MSG far* msg);

Description

Responds to WM_GETDLGCODE messages that are sent to a dialog box associated with a control. EvGetDlgCode  allows the dialog manager to intercept a message that would normally go to a control and then ask the control if it wants to process this message. If not, the dialog manager processes the message. The msg parameter indicates the kind of message, for example a control, command, or edit message, sent to the dialog box manager.

If the edit control contains valid input, then Tabs are allowed for changing focus and a DLGC_WANTTABS code is returned.


See Also

DLGC_xxxxdialogcontrolmessageconstants


TEdit::EvKillFocus

TEdit

Syntax

void EvKillFocus(HWND hWndGetFocus);

Description

In response to a WM_KILLFOCUS message sent to a window that is losing the keyboard, EvKillFocus hides and then destroys the caret. EvKillFocus validates text whenever the focus is about to be lost and holds onto the focus if the text is not valid. Doesn't kill the focus if another application, a Cancel button, or an OK button (in which case CanClose is called to validate text) has the focus.


TEdit::GetClassName

See Also	TEdit

Syntax

char far* GetClassName();

Description

Returns the name of TEdit's registration class, "EDIT."


See Also

TWindow::GetClassName


TEdit::SetupWindow

See Also	TEdit

Syntax

void SetupWindow();

Description

If the textLen data member is nonzero, SetupWindow limits the number of characters that can be entered into the edit control to textLen -1.


See Also

TStatic::TextLen

TWindow::SetupWindow


TEdit Response Table Entries

TEdit

Response table entry	Member function

EV_COMMAND (CM_EDITCLEAR, CmEditClear)	CmEditClear

EV_COMMAND (CM_EDITCOPY, CmEditCopy)	CmEditCopy

EV_COMMAND (CM_EDITCUT, CmEditCut)	CmEditCut

EV_COMMAND (CM_EDITDELETE, CmEditDelete)	CmEditClear

EV_COMMAND (CM_EDITPASTE, CmEditPaste)	CmEditPaste

EV_COMMAND (CM_EDITUNDO, CmEditUndo)	CmEditUndo

EV_COMMAND_ENABLE(CM_EDITCLEAR, CmCharsEnable)	CmCharsEnable

EV_COMMAND_ENABLE(CM_EDITCOPY, CmSelectEnable)	CmSelectEnable

EV_COMMAND_ENABLE(CM_EDITCUT, CmSelectEnable)	CmSelectEnable

EV_COMMAND_ENABLE(CM_EDITDELETE, CmSelectEnable)	CmSelectEnable

EV_COMMAND_ENABLE(CM_EDITPASTE, CmPasteEnable)	CmPasteEnable

EV_COMMAND_ENABLE(CM_EDITUNDO, CmModEnable)	CmModEnable

EV_NOTIFY_AT_CHILD (EN_ERRSPACE, ENErrSpace)	ENErrSpace

EV_WM_CHAR	EvChar

EV_WM_GETDLGCODE	EvGetdlgcode

EV_WM_KEYDOWN	EvKeydown

EV_WM_KILLFOCUS	EvKillFocus

EV_WM_CHILDINVALID	EvChildInvalid


TEditFile class

OWL Hierarchy	Inheritance

Header File

editfile.h

Description

TEditFile is a file-editing window. TEditFile's data members and member functions manage the file dialog box and automatic responses for file commands such as Open, Read, Write, Save, and SaveAs. TEditFile is streamable.

Public data members

TOpenSaveDialog::TData FileData;

char far* FileName;

Public constructors and destructor

TEditFile(TWindow* ()t = 0, int Id = 0, const char far* text = 0, const char far* fileName =

~TEditFile();0, TModule* module = 0);

Public member functions

virtual bool CanClear();

virtual bool CanClose();

void CmFileNew();

void CmFileOpen();

void CmFileSave();

void CmFileSaveAs();

void NewFile();

Open();

bool Read(const char far* fileName=0);

void ReplaceWith(const char far* fileName);

bool Save();

bool SaveAs();

void SetFileName (const char far* fileName);

bool Write(const char far* fileName=0);

Protected member functions

void SetupWindow();

Response Table Entries

EV_ macros and member functions


TEditFile::FileData

See Also	TEditFile

Syntax

TOpenSaveDialog::TData FileData;

Description

Contains information about the user's file open or save selection.


See Also

TOpenSaveDialog::TData struct


TEditFile::FileName

TEditFile

Syntax

char far* FileName;

Description

Contains the name of the file being edited.


TEditFile Public constructors and destructor

TEditFile

Syntax

TEditFile(TWindow* ()t = 0, int Id = 0, const char far* text = 0, const char far* fileName = 0, TModule* module = 0);

Destructor

~TEditFile();

Description

Constructs a TEditFile window given the parent window, resource ID (Id), text, file name, and module ID. Sets Filename to fileName.

Destructor

Frees memory allocated to hold the name of the TEditFile.


TEditFile::CanClear

TEditFile

Syntax

virtual bool CanClear();

Description

Returns true if the text of the associated edit control can be cleared.


TEditFile::CanClose

TEditFile

Syntax

virtual bool CanClose();

Description

Returns true if the edit window can be closed.


TEditFile::CmFileNew

See Also	TEditFile

Syntax

void CmFileNew();

Description

Calls NewFile in response to an incoming File New command with a CM_FILENEW command identifier.


See Also

TEditFile::NewFile


TEditFile::CmFileOpen

See Also	TEditFile

Syntax

void CmFileOpen();

Description

Calls Open in response to an incoming File Open command with a CM_FILEOPEN command identifier.


See Also

TEditFile::Open


TEditFile::CmFileSave

See Also	TEditFile

Syntax

void CmFileSave();

Description

Calls Save in response to an incoming File Save command with a CM_FILESAVE command identifier.


See Also

TEditFile::Save


TEditFile::CmFileSaveAs

See Also	TEditFile

Syntax

void CmFileSaveAs();

Description

Calls SaveAs in response to an incoming File SaveAs command with a CM_FILESAVEAS command identifier.


See Also

TEditFile::SaveAs


TEditFile::NewFile

See Also	TEditFile

Syntax

void NewFile();

Description

Begins the edit of a new file after calling CanClear to determine that it is safe to clear the text of the editor.


See Also

TEditFile::CanClear


TEditFile::Open

See Also	TEditFile

Syntax

Open();

Description

Opens a new file after determining that it is OK to clear the text of the Editor. Calls CanClear, and if true is returned, brings up a file dialog box to retrieve the name of a new file from the user. Calls ReplaceWith to pass the name of the new file.


See Also

TEditFile::CanClear

TEditFile::ReplaceWith


TEditFile::Read

TEditFile

Syntax

bool Read(const char far* fileName=0);

Description

Reads the contents of a previously specified file into the Editor. Returns true if read operation is successful.


TEditFile::ReplaceWith

See Also	TEditFile

Syntax

void ReplaceWith(const char far* fileName);

Description

Calls SetFileName and Read to replace the file currently being edited with a file whose name is supplied.


See Also

TEditFile::SetFileName

TEditFile::Read


TEditFile::Save

See Also	TEditFile

Syntax

bool Save();

Description

Saves changes to the contents of the Editor to a file. If Editor->IsModified returns false, Save returns true, indicating there have been no changes since the last open or save.


See Also

TEditFile::SaveAs

TEditFile::Write


TEditFile::SaveAs

See Also	TEditFile

Syntax

bool SaveAs();

Description

Saves the contents of the Editor to a file whose name is retrieved from the user, through execution of a File Save dialog box. If the user selects OK, SaveAs calls SetFileName and Write. Returns true if the file was saved.


See Also

TEditFile::SetFileName

TEditFile::Write


TEditFile::SetFileName

TEditFile

Syntax

void SetFileName (const char far* fileName);

Description

Sets FileName and updates the caption of the window.


TEditFile::Write

TEditFile

Syntax

bool Write(const char far* fileName=0);

Description

Saves the contents of the Editor to a file whose name is specified by FileName. Returns true if the write operation is successful.


TEditFile::SetupWindow

See Also	TEditFile

Syntax

void SetupWindow();

Description

Creates the edit window's Editor edit control by calling TEditFile::SetupWindow. Sets the window's caption to FileName, if available; otherwise sets the name to "Untitled."


See Also

TEditFile::SetFileName

TEditFile::Read


TEditFile::Response table entries
TEditFile Response table entries

TEditFile

Response table entry	Member function

EV_COMMAND (CM_FILENEW, CmFileNew)	CmFileNew

EV_COMMAND (CM_FILEOPEN, CmFileOpen)	CmFileOpen

EV_COMMAND (CM_FILESAVE, CmFileSave)	CmFileSave

EV_COMMAND (CM_FILESAVEAS, CmFileSaveAs)	CmFileSaveAs


TEditSearch Class

OWL Hierarchy	Inheritance

Header File

editsear.h

Description

TEditSearch is an edit control that responds to Find, Replace, and FindNext menu commands. This class is streamable.

Public Data Members

uint SearchCmd;

TFindReplaceDialog::TData SearchData;

TFindReplaceDialog* SearchDialog;

Public Constructors

TEditSearch(TWindow* parent = 0, int Id = 0, const char far* text = 0, int x = 0, int y = 0, int w = 0, int h = 0, TModule* module = 0);

Public Member Functions

void CmEditFind();

void CmEditFindNext();

void CmEditReplace();

void DoSearch();

LRESULT EvFindMsg(WPARAM, LPARAM);

void SetupWindow();

Response Table Entries

EV_ macros and member functions


TEditSearch::SearchCmd

TEditSearch

Syntax

uint SearchCmd;

Description

Contains the search command identifier that opened the dialog box if one is open.


TEditSearch::SearchData

See Also	TEditSearch

Syntax

TFindReplaceDialog::TData SearchData;

Description

The SearchData structure defines the search text string, the replacement text string, and the size of the text buffer.


See Also

TFindReplaceDialog::TData


TEditSearch::SearchDialog

TEditSearch

Syntax

TFindReplaceDialog* SearchDialog;

Description

Contains find or replace dialog-box information (such as the text to find and replace) and check box settings.


 TEditSearch Public Constructor

TEditSearch

Syntax

TEditSearch(TWindow* parent = 0, int Id = 0, const char far* text = 0, int x = 0, int y = 0, int w = 0, int h = 0, TModule* module = 0);

Description

Constructs a TEditSearch object given the parent window, resource ID, and character string (text).


TEditSearch::CmEditFind

TEditSearch

Syntax

void CmEditFind();

Description

Opens a TFindDialog in response to an incoming Find command with a CM_EDITFIND command.


TEditSearch::CmEditFindNext

See Also	TEditSearch

Syntax

void CmEditFindNext();

Description

Responds to an incoming FindNext command with a CM_EDITFINDNEXT command identifier by calling DoSearch to repeat the search operation.


See Also

TEditSearch::DoSearch


TEditSearch::CmEditReplace

TEditSearch

Syntax

void CmEditReplace();

Description

Opens a TReplaceDialog in response to an incoming Replace command with a CM_EDITREPLACE command.


TEditSearch::DoSearch

See Also	TEditSearch

Syntax

void DoSearch();

Description

Performs a search or replace operation base on information in SearchData.


See Also

TFindReplaceDialog::TData


TEditSearch::EvFindMsg

See Also	TEditSearch

Syntax

LRESULT EvFindMsg(WPARAM, LPARAM);

Description

Responds to a message sent by the modeless find or replace dialog box. Calls DoSearch to continue searching if text is not found or the end of the document has not been reached.


See Also

TEditSearch::DoSearch


TEditSearch::SetupWindow

See Also	TEditSearch

Syntax

void SetupWindow();

Description

Posts a CM_EDITFIND or a CM_EDITREPLACE message to re-open a find or replace modeless dialog box. Calls TEdit::SetupWindow.


See Also

TEdit::SetupWindow


TEditSearch::Response Table Entries

TEditSearch

Response table entry	Member function

EV_COMMAND(CM_EDITFIND, CmEditFind)	CmEditFind

EV_COMMAND(CM_EDITFINDNEXT, CmEditFindNext)	CmEditFindNext

EV_COMMAND(CM_EDITREPLACE, CmEditReplace)	CmEditReplace

EV_REGISTERED(FINDMSGSTRING, EvFindMsg)	EvFindMsg


TEditView Class

OWL Hierarchy	Inheritance

Header File

editview.h

Description

Derived from TView and TEditSearch, TEditView provides a view wrapper for the ObjectWindows text edit class (TEdit). A streamable class, TEditView includes several event-handling functions that handle messages between a document and its views.

Public Constructor and Destructor

TEditView(TDocument& doc, TWindow* parent = 0);

~TEditView()

Public Member Functions

bool CanClose();

bool Create()

const far char* GetViewName();

TWindow* GetWindow();

void PerformCreate(int menuOrId);

bool SetDocTitle(const far char* docname, int index);

static const far char* StaticName();

Protected Data Member

long Origin;

Protected Member Functions

void EvNCDestroy();

bool LoadData();

bool VnCommit(bool force);

bool VnDocClosed(int omode);

bool VnIsDirty();

bool VnIsWindow(HWND hWnd);

bool VnRevert(bool clear);

Response Table Entries

EV_ macros and member functions


TEditView Public Constructor and Destructor

TEditView

Constructor Syntax

TEditView(TDocument& doc, TWindow* parent = 0);

Description

Creates a TEditView object associated with the specified document and parent window. Sets AttrAccelTable to IDA_EDITVIEW to identify the edit view. Sets the TView private data member ViewMenu to the new TMenuDescr for this view.

Destructor Syntax

~TEditView()

Description

Destroys a TEditView object.


TEditView::CanClose

TEditView

Syntax

bool CanClose();

Description

Returns a nonzero value if the view can be closed.


TEditView::Create

TEditView

Syntax

bool Create()

Description

Creates the view's window. Calls GetDocPath to determine if the file is new or if it already has data. If there is data, calls LoadData to add the data to the view. If the view's window cannot be created, Create indicates that the view is invalid.


TEditView::GetViewName

See Also	TEditView

Syntax

const far char* GetViewName();

Description

Overrides TView::GetViewName and returns the descriptive name of the class ("StaticName").


See Also

TEditView::StaticName

TView::GetViewName


TEditView::GetWindow

See Also	TEditView

Syntax

TWindow* GetWindow();

Description

Overrides TView::GetWindow and returns this as a TWindow.


See Also

TView::GetWindow


TEditView::PerformCreate

TEditView

Syntax

void PerformCreate(int menuOrId);

Description

Allocates memory as necessary so that TEditView can handle files up to and including 30,000 bytes.


TEditView::SetDocTitle

See Also	TEditView

Syntax

bool SetDocTitle(const far char* docname, int index)

Description

Overrides TView::SetDocTitle and forwards the title to its base class, TEditSearch. index is the number of the view displayed in the caption bar. docname is the name of the document displayed in the view window.


See Also

TWindow::SetDocTitle

TView::SetDocTitle


TEditView::StaticName

TEditView

Syntax

static const far char* StaticName();

Description

Returns "Edit View", the descriptive name of the class for the ViewSelect menu.


TEditView::Origin

TEditView

Syntax

long Origin;

Description

Holds the file position at the beginning of the display.


TEditView::EvNCDestroy

TEditView

Syntax

void EvNCDestroy();

Description

Used internally by TEditView to manage memory.

This member is not available under Presentation Manager.


TEditView::LoadData

TEditView

Syntax

bool LoadData();

Description

Reads the view from the stream and closes the file. It returns a nonzero value if the view was successfully loaded. If the file cannot be read, LoadData posts an error and returns 0.


TEditView::VnCommit

See Also	TEditView

Syntax

bool VnCommit(bool force);

Description

Commits changes made in the view to the document. If force is nonzero, all data, even if unchanged, is saved to the document.


See Also

TEditView::vnRevert

vnxxxx view notification constants


TEditView::VnDocClosed

See Also	TEditView

Syntax

bool VnDocClosed(int omode);

Description

Indicates that the document has been closed. mode is one of the ofxxxx document open enum constants.


See Also

vnxxxx view notification constants


TEditView::VnIsDirty

See Also	TEditView

Syntax

bool VnIsDirty();

Description

Returns a nonzero value if changes made to the data in the view have not been saved to the document; otherwise, it returns 0.


See Also

vnxxxx view notification constants


TEditView::VnIsWindow

TEditView

Syntax

bool VnIsWindow(HWND hWnd);

Description

Returns a nonzero value if the window's handle passed in hWnd is the same as that of the view's display window.


TEditView::VnRevert

See Also	TEditView

Syntax

bool VnRevert(bool clear);

Description

Returns a nonzero value if changes made to the view should be erased and the data from the document should be restored to the view. If clear is nonzero, the data is cleared instead of restored to the view.


See Also

TEditView::VnCommit


TEditView Response Table Entries

TEditView

Response table entry	Member function

EV_VN_COMMIT	VnCommit

EV_VN_DOCCLOSED	VnDocClosed

EV_VN_ISDIRTY	VnIsDirty

EV_VN_ISWINDOW	VnIsWindow

EV_WM_NCDESTROY	EvNCDestroy

EV_VN_REVERT	VnRevert


TEventHandler TEqualOperator typedef
TEqualOperator typedef

OWL Hierarchy

Header File

eventhan.h

Syntax

typedef bool(*TEqualOperator)(TGenericTableEntry __RTFAR&, TEventInfo&);

Description

TEqualOperator is used to perform special kinds of searches and to faciliate finding response table entries. TEqualOperator compares a particular message event (TEventInfo&) with a response table entry (TGenericTableEntry) to determine if they match.


See Also

TResponseTableEntry


TEventHandler::TEventInfo class

TEventHandler

Header File

eventhan.h

Description

A nested class, TEventInfo provides specific information about the type of message sent, the class that contains the function to be handled, the corresponding response table entry, and the dispatch function that processes the message.

Public Data Members

TGenericTableEntry __RTFAR *Entry;

TEventStatus enum

const uint Id;

const uint Msg;

GENERIC *Object;

Public Constructor

TEventInfo(uint msg, uint id = 0) : Msg(msg), Id(id);


TEventHandler::Msg
TEventHandler::TEventInfo::Msg

TEventHandler::TEventInfo

Syntax

const uint Msg;

Description

Contains the type of message sent. These can be command messages, child ID messages, notify-based messages such as LBN_SELCHANGE, or windows messages such as LBUTTONDOWN.


TEventHandler::Id
TEventHandler::TEventInfo::Id

TEventHandler::TEventInfo

Syntax

const uint Id;

Description

Contains the menu or accelerator resource ID (CM_xxxx) for the message response member function.


TEventHandler::Object
TEventHandler::TEventInfo::Object

TEventHandler::TEventInfo

Syntax

GENERIC *Object;

Description

Points to the object that contains the function to be handled.


TEventHandler::Entry
TEventHandler::TEventInfo::Entry

TEventHandler::TEventInfo

Syntax

TGenericTableEntry __RTFAR *Entry;

Description

Points to the response table entry (for example, EvActivate).


TEventStatus enum

TEventHandler::TEventInfo

Header File

window.h

Syntax

enum TEventStatus{esPartial, esComplete};

Description

Event status constants indicate the status of a mix-in window event implementation, for example, a keyboard event. The TEventStatus constants indicate whether or not additional handlers are needed.

Event Status Constants

Constant	Meaning

esPartial	Additional handlers can be invoked

esComplete	No additional handlers are needed


TEventHandler::TEventInfo Public Constructor

TEventHandler::TEventInfo

Syntax

TEventInfo(uint msg, uint id = 0) : Msg(msg), Id(id);

Description

Constructs a TEventInfo object with the specified ID and message type.


TEventHandler Class

OWL Hierarchy	Inheritance

Header File

eventhan.h

Description

TEventHandler is a base class from which you can derive classes that handle messages. Specifically, TEventHandler performs the following event-handling tasks:

1.	Analyzes a window message.

2.	Searches the class's response table entries for an appropriate event-handling function.

3.	Dispatches the message to the designated event-handling function.

Most of ObjectWindows' classes are derived from TEventHandler and, therefore, inherit this event-handling behavior. In addition, any user-defined class derived from TEventHandlercan handle message response functions that are associated with a particular window message.

Public Member Functions

virtual LRESULT Dispatch(TEventInfo&, WPARAM, LPARAM = 0);

virtual bool Find(TEventInfo&, TEqualOperator = 0);

Protected Member Function

bool SearchEntries(TGenericTableEntry __RTFAR* entries, TEventInfo&, TEqualOperator);


TEventHandler::Dispatch

TEventHandler

Syntax

virtual LRESULT Dispatch(TEventInfo&, WPARAM, LPARAM = 0);

Description

Takes the message data from TEventInfo's Msg data member and dispatches it to the correct event handling function.


TEventHandler::Find

TEventHandler

Syntax

virtual bool Find(TEventInfo&, TEqualOperator = 0);

Description

Searches the list of response table entries looking for a match. Because TEventHandler doesn't have any entries, TEventHandler's implementation of this routine returns false.


TEventHandler::SearchEntries

See Also	TEventHandler

Syntax

bool SearchEntries(TGenericTableEntry __RTFAR* entries, TEventInfo&, TEqualOperator);

Description

Searches the entries in the response table for an entry that matches TEventInfo or, if so designated, an entry that TEqualOperator specifies is a match.


See Also

DECLARE_RESPONSE_TABLE macro


TFileDocument Class

OWL Hierarchy	Inheritance

Header File

filedoc.h

Description

Derived from TDocument, TFileDocument opens and closes views and provides stream support for views. TFileDocument has member functions that continue to process FileNew and FileOpen messages after a view is constructed. You can add support for specialized file types by deriving classes from TFileDocument. TFileDocument makes this process easy by hiding the actual process of storing file types.

Type Definitions

enum TFileDocProp{PrevProperty, CreateTime, ModifyTime, AccessTime, StorageSize, FileHandle, NextProperty};

Public Constructor and Destructor

TFileDocument(TDocument* parent = 0);

~TFileDocument();

Public Member Functions

bool Close();

bool Commit(bool force = false);

int FindProperty(const char far* name);

int GetProperty(int index, void far* dest, int textlen=0);

TInStream* InStream(int mode, const char far* strmId = 0);

bool IsOpen();

bool Open(HFILE fhdl);

bool Open(int mode, const char far* path=0);

TOutStream* OutStream (int mode, const char far* strmId = 0);

int PropertyFlags(int index);

const char* PropertyName(int index);

bool Revert(bool clear = false);

bool SetProperty(int index, const void far* src);

Protected Data Member

HFILE FHdl;

Protected Member Functions

void CloseThisFile(HFILE fhdl, int omode);

HFILE OpenThisFile(int omode, const char far* name, streampos* pseekpos);


TFileDocument::TFileDocProp enum

TFileDocument

Syntax

enum TFileDocProp {PrevProperty, CreateTime, ModifyTime, AccessTime, StorageSize, FileHandle, NextProperty};

Description

Contains constants that define the following properties of the document:

Value	Description

PrevProperty	TDocument::NextProperty-1. This is the first value for view and document objects.

CreateTime	The time the view or document was created.

ModifyTime	The time the view or document was modified.

AccessTime,	The time the view or document was last accessed.

StorageSize	An unsigned long containing the storage size.

FileHandle	The platform file handle.

NextProperty	The terminating  value for the property.

Classes derived from TDocument and  TView can use these generic file property values.


TFileDocument Public Constructors and Destructor
TFileDocument Public Constructor and Destructor

TFileDocument

Constructor

TFileDocument(TDocument* parent = 0);

Description

Constructs a TFileDocument object with the optional parent document.

Destructor

~TFileDocument(TDocument* parent = 0);

Description

Destroys a TFileDocument object.


TFileDocument::Close

TFileDocument

Syntax

bool Close();

Description

Closes the document but does not delete or detach any associated views. Before closing the document, Close calls TDocument::Close to make sure all child documents are closed. If any children are open, Close returns 0 and does not close the document. If all children are closed, Close checks to see if any associated streams are open, and if so, returns 0 and does not close the document. If there are no open streams, Close closes the file.


TFileDocument::Commit

TFileDocument

Syntax

bool Commit(bool force = false);

Description

Calls TDocument::Commit and clears TDocument's DirtyFlag data member, thus indicating that there are no unsaved changes made to the document.


TFileDocument::FindProperty

See Also	TFileDocument

Syntax

int FindProperty(const char far* name);

Description

Gets the property index, given the property name (name). Returns 0 if the name is not found.


See Also

pfxxxx property attribute constants


TFileDocument::GetProperty

See Also	TFileDocument

Syntax

int GetProperty(int index, void far* dest, int textlen=0);

Description

Overrides TDocument::GetProperty and gets the property ID for the current file document.


See Also

pfxxxx property attribute constants


TFileDocument::InStream

See Also	TFileDocument

Syntax

TInStream* InStream(int mode, const char far* strmId = 0);

Description

Overrides TDocument::InStream and provides generic input for the particular storage medium. InStream returns a pointer to a TInStream. mode is a combination of the ios bits defined in iostream.h. strmId is not used for file documents. The view reads data from the document as a stream or through stream functions.


See Also

TFileDocument::OutStream


TFileDocument::IsOpen

TFileDocument

Syntax

bool IsOpen();

Description

Is nonzero if the document or any streams are open.


TFileDocument::Open

See Also	TFileDocument

Syntax 1

bool Open(HFILE fhdl);

Description

Opens a file document using an existing file handle. Sets TDocument::OpenMode to PREV_OPEN and read/write. Sets the document path to 0. Sets FHdl to fhdl. Always returns a nonzero value.

Syntax 2

bool Open(int mode, const char far* path=0);

Description

Overrides TDocument::Open and opens the file using the specified path. If the file is already open, returns 0. Calls TDocument::SetDocPath to set the directory path. If mode is not 0, sets TDocument::OpenMode to mode. If the file cannot be opened, returns 0.


See Also

ofxxxx document open enum


TFileDocument::OutStream

See Also	TFileDocument

Syntax

TOutStream* OutStream (int mode, const char far* strmId = 0);

Description

Overrides TDocument::OutStream and provides generic input for the particular storage medium. OutStream returns a pointer to a TOutStream. mode is a combination of the ios bits defined in iostream.h. strmId is not used for file documents. Instead, the view reads data from the document through stream functions.


See Also

TFileDocument::InStream


TFileDocument::PropertyFlags

See Also	TFileDocument

Syntax

int PropertyFlags(int index);

Description

Returns the property attribute constants (pfGetText, pfHidden, and so on).


See Also

pfxxxx property attribute constants


TFileDocument::PropertyName

See Also	TFileDocument

Syntax

const char* PropertyName(int index);

Description

Returns the text name of the property given the index value.


See Also

pfxxxx property attribute constants


TFileDocument::Revert

See Also	TFileDocument

Syntax

bool Revert(bool clear = false);

Description

Calls TDocument::Revert to notify the views to refresh their data. If clear is false, the data is restored instead of cleared.


See Also

TFileDoc::Commit


TFileDocument::SetProperty

See Also	TFileDocument

Syntax

bool SetProperty(int index, const void far* src);

Description

Sets the property data, which must be in the native data type (either string or binary).


See Also

pfxxxx property attribute constants


TFileDocument::FHdl

TFileDocument

Syntax

HFILE FHdl;

Description

Holds the file handle to an open file document.


TFileDocument::CloseThisFile

See Also	TFileDocument

Syntax

void CloseThisFile(HFILE fhdl, int omode);

Description

Closes the file handle if the associated file was opened by TFileDocument. Calls TDocument::NotifyViews to notify all views that the file document has closed.


See Also

ofxxxx document open enum


TFileDocument::OpenThisFile

See Also	TFileDocument

Syntax

HFILE OpenThisFile(int omode, const char far* name, streampos* pseekpos);

Description

Opens the file document after checking the file sharing mode (omode).  If a file mode is not specified as read, write, or read and write, OpenThisFile returns 0.


See Also

ofxxxx document open enum

shxxxx document sharing modes


TFileOpenDialog Class

OWL Hierarchy	Inheritance

Header File

opensave.h

Description

TFileOpenDialog is a modal dialog box that lets you specify the name of a file to open. Use this dialog box to respond to a CM_FILEOPEN command that's generated when a user selects File|Open from a menu. TFileOpenDialog  uses the TOpenSave::TDatastructure to initialize the file open dialog box.

Public Constructor

TFileOpenDialog(TWindow* parent, TData& data, TResID templateID = 0, const char far* title, TModule* module = 0);

Public Member Function

int DoExecute();= 0


TFileOpenDialog Public Constructor

See Also	TFileOpenDialog

Syntax

TFileOpenDialog(TWindow* parent, TData& data, TResID templateID = 0, const char far* title = 0, TModule* module = 0);

Description

Constructs and initializes the TFileOpen object based on information in the TOpenSaveDialog::TData data structure. The parent argument points to the dialog box's parent window. data is a reference to the TData object. templateID is the ID for a custom template. title is an optional title. module points to the module instance.


See Also

TOpenSaveDialog::TData

TOpenSaveDialog

TResID

TModule


TFileOpenDialog::DoExecute

See Also	TFileOpenDialog

Syntax

int DoExecute();

Description

Creates the TFileOpenDialog object.


See Also

TDialog::DoExecute


TFileSaveDialog Class

OWL Hierarchy	Inheritance

Header File

opensave.h

Description

TFileSaveDialog is a modal dialog box that lets you enter the name of a file to save. Use TFileSaveDialog to respond to a CM_FILESAVEAS command generated when a user selects File|Save from a menu. TFileSaveDialog uses the TOpenSave::TData structure to initialize the file save dialog box.

Public Constructor

TFileSaveDialog(TWindow* parent, TData& data, TResID templateID = 0, const char far* title = ;0, TModule* module = 0);

Public Member Function

int DoExecute();


TFileSaveDialog Public Constructor

See Also	TFileSaveDialog

Syntax

TFileSaveDialog(TWindow* parent, TData& data, TResID templateID = 0, const char far* title = 0, TModule* module = 0);

Description

Constructs and initializes the TFileOpen object based on the TOpenSaveDialog::TData  structure, which contains information about the file name, file directory, and file name search filers.


See Also

TOpenSaveDialog::TData structure

TModule

TResID

TWindow


TFileSaveDialog::DoExecute

See Also	TFileSaveDialog

Syntax

int DoExecute();

Description

Creates the TFileSaveDialog object.


See Also

TDialog::DoExecute

TOpenSaveDialog


TFilterValidator Class

OWL Hierarchy	Inheritance

Header File

validate.h

Description

A streamable class, TFilterValidator checks an input field as the user types into it. The validator holds a set of allowed characters. When the user enters a character, the filter validator indicates whether the character is valid or invalid. See TValidator for an example of input validation.

Public Constructor

TFilterValidator(const TCharSet& validChars);

Public Member Functions

void Error();

bool IsValid(const char far* str);

bool IsValidInput(char far* str, bool suppressFill);

Protected Data Members

TCharSet ValidChars;


TFilterValidator Public Constructor

TFilterValidator

Syntax

TFilterValidator(const TCharSet& validChars);

Description

Constructs a filter validator object by first calling the constructor inherited from TValidator, then setting ValidChars to validChars.


TFilterValidator::Error

See Also	TFilterValidator

Syntax

void Error();

Description

Error overrides TValidator's virtual function and displays a message box indicating that the text string contains an invalid character.


See Also

TValidator::Error


TFilterValidator::IsValid

TFilterValidator

Syntax

bool IsValid(const char far* str);

Description

IsValid overrides TValidator's virtuals and returns true if all characters in str are in the set of allowed characters, ValidChar; otherwise, it returns false.


TFilterValidator::IsValidInput

See Also	TFilterValidator

Syntax

bool IsValidInput(char far* str, bool suppressFill);

Description

IsValidInput overrides TValidator's virtual function and checks each character in the string str to ensure it is in the set of allowed characters, ValidChar. IsValidInput returns true if all characters in str are valid; otherwise, it returns false.


See Also

TValidator::IsValidInput


TFilterValidator::ValidChars

TFilterValidator

Syntax

TCharSet ValidChars;

Description

Contains the set of all characters the user can type. For example, to allow only numeric digits, set ValidChars to "0-9". ValidChars is set by the validChars parameter passed to the constructor.


TFindDialog Class

OWL Hierarchy	Inheritance

Header File

findrepl.h

Description

TFindDialog objects represents modeless dialog box interface elements that let you specify text to find. TFindDialog communicates with the owner window using a registered message. Derived from  TFindReplaceDialog , TFindDialog uses the  TFindReplaceDialog::TData  structure to initialize the dialog box with user-entered values (such as the text string to find).

Public Constructor

TFindDialog(TWindow* parent, TData& data, TResId templateId = 0, const char far* title = 0, TModule* );

Protected Member Functions

HWND DoCreate();


TFindDialog::TFindDialog

See Also	TFindDialog

Constructor

TFindDialog(TWindow* parent, TData& data, TResId templateId = 0, const char far* title = 0, TModule* module = 0);

Description

Constructs a TFindDialog object with the given parent window, resource ID, and caption. Sets the attributes of the dialog box based onTFindReplaceDialog::TData structure, which contains information about the text string to search for.


See Also

TFindReplaceDialog::TData


TFindDialog::DoCreate

TFindDialog

Syntax

HWND DoCreate();

Description

Creates the modeless interface element of a find dialog.


TFindReplaceDialog Class

OWL Hierarchy	Inheritance

Header File

findrepl.h

Description

TFindReplaceDialog is an abstract base class for a modeless dialog box that lets you search for and replace text. This base class contains functionality common to both derived classes, TFindDialog (lets you specify text to find) and TReplaceDialog (lets you specify replacement text). TFindReplaceDialog communicates with the owner window using a registered message.

Public Constructor

TFindReplaceDialog(TWindow* ()t, TData& data, TResId templateId = 0, const char far* title

Public Member Functions

void CmCancel();= 0, TModule* module = 0);

void CmFindNext();

void CmReplace();

void CmReplaceAll();

void EvNCDestroy();

Protected Data Members

TData& Data;

FINDREPLACE fr;

Protected Member Functions

HWND DoCreate()=0;

bool DialogFunction(uint message, WPARAM, LPARAM);

void Init(TResId templateId);

Response Table Entries

EV_ macros and member functions


TFindReplaceDialog Public Constructor

See Also	TFindReplaceDialog

Syntax

TFindReplaceDialog(TWindow* parent, TData& data, TResId templateId = 0, const char far* title = 0, TModule* module = 0);

Description

Constructs a TFindReplaceDialog object with a parent window, resource ID, and caption. Sets the attributes of the dialog box with the specified data from the  TFindReplaceDialog::TData  structure.


See Also

TFindReplaceDialog::TData struct

TModule

TResID

TWindow


TFindReplaceDialog::CmCancel

TFindReplaceDialog

Syntax

void CmCancel();

Description

Responds to a click of the Cancel button.


TFindReplaceDialog::CmFindNext

TFindReplaceDialog

Syntax

void CmFindNext();

Description

Responds to a click of the Find Next button.


TFindReplaceDialog::CmReplace

TFindReplaceDialog

Syntax

void CmReplace();

Description

Responds to a click of the Replace button.


TFindReplaceDialog::CmReplaceAll

TFindReplaceDialog

Syntax

void CmReplaceAll();

Description

Responds to a click of the Replace All button.


TFindReplaceDialog::EvNCDestroy

TFindReplaceDialog

Syntax

void EvNCDestroy();

Description

Calls TWindow::EvNCDestroy, which responds to an incoming EV_WM_NCDESTROY message which tells the owner window that is nonclient area is being destroyed.


TFindReplaceDialog::Data

See Also	TFindReplaceDialog

Syntax

TData& Data;

Description

Data is a reference to the TData object passed in the constructor.


See Also

TFindReplaceDialog::TData class


TFindReplaceDialog::fr

See Also	TFindReplaceDialog

Syntax

FINDREPLACE fr;

Description

A struct that contains find-and-replace attributes, such as the size of the find buffer and pointers to search and replace strings, used for find-and-replace operations.


See Also

FINDREPLACE class


TFindReplaceDialog::DoCreate

TFindReplaceDialog

Syntax

HWND DoCreate()=0;

Description

DoCreate is a virtual function that is overridden in derived classes to create a modeless find or replace dialog box.


TFindReplaceDialog::DialogFunction

See Also	TFindReplaceDialog

Syntax

bool DialogFunction(uint message, WPARAM, LPARAM);

Description

Returns true if a message is handled.


See Also

TDialog::DialogFunction


TFindReplaceDialog::Init

TFindReplaceDialog

Syntax

void Init(TResId templateId);

Description

Used by constructors in derived classes, Init initializes a TFindReplaceDialog object with the current resource ID and other members.


TFindReplaceDialog::Response Table Entries

TFindReplaceDialog

Response table entry	Member function

EV_WM_NCDESTROY	EvNCDestroy


TFindReplaceDialog::TData class

TFindReplaceDialog

Header File

findrepl.h

Description

The TFindReplaceDialog::TData class encapsulates information necessary to initialize a TFindReplace dialog box. The TFindDialog and TReplaceDialog classes use the TFindReplaceDialog::TData  class to initialize the dialog box and to accept user-entered options such as the search and replacement text strings.

Public Constructor and Destructor

TFindReplaceDialog::TData(uint32 flags = 0, int bufferSize = 81);

~TData();

Public Data Members

int BuffSize;

uint32 Error;

char* FindWhat;

uint32 Flags;

char* ReplaceWith;


TFindReplaceDialog::TData Public Constructor and Destructor

Constructor

TFindReplaceDialog(uint32 flags = 0, int bufferSize = 81);

Destructor

~TData();

Description

Constructs a TData object with the specified flag value that initializes the status of the dialog box control buttons and the buffer size for the find and replace search strings.

Destructor

Destroys a ~TData object.


TFindReplaceDialog::TData::BuffSize

TFindReplaceDialog::TData

Syntax

int BuffSize;

Description

BuffSize contains the size of the text buffer.


TFindReplaceDialog::TData::Error

TFindReplaceDialog::TData

Syntax

uint32 Error;

Description

If the dialog box is successfully created, Error  is 0. Otherwise, it contains one or more of the following error codes:

Constant	Meaning

CDERR_LOCKRESOURCEFAILURE	Failed to lock a specified resource.

CDERR_LOADRESFAILURE	Failed to load a specified resource.

CDERR_LOADSTRFAILURE	Failed to load a specified string.

CDERR_REGISTERMSGFAIL	The window message (a value used to communicate between applications) cannot be registered. This message value is used when sending or posting window messages.


TFindReplaceDialog::TData::FindWhat

TFindReplaceDialog::TData

Syntax

char* FindWhat;

Description

Contains the search string.


TFindReplaceDialog::TData::Flags

TFindReplaceDialog::TData

Syntax

uint32 Flags;

Description

Flags, which indicates the state of the control buttons and the action that occurred in the dialog box, can be a combination of the following constants that indicate which command the user wants to select:

Constant	Meaning

FR_DOWN	The Down button in the Direction group of the Find dialog box is selected.

FR_HIDEMATCHCASE	The Match Case check box is hidden.

FR_HIDEWHOLEWORD	The Whole Word check box is hidden.

FR_HIDEUPDOWN.	The Up and Down buttons are hidden.

FR_MATCHCASE	The Match Case check box is checked.

FR_NOMATCHCASE	The Match Case check box is disabled. This occurs when the dialog box is first initialized.

FR_NOUPDOWN	The Up and Down buttons are disabled. This occurs when the dialog box is first initialized.

FR_NOWHOLEWORD	The Whole Word check box is disabled. This occurs when the dialog box is first initialized.

FR_REPLACE	The Replace button was pressed in the Replace dialog box.

FR_REPLACEALL	The Replace All button was pressed in the Replace dialog box.

FR_WHOLEWORD	The Whole Word check box is checked.


TFindReplaceDialog::TData::ReplaceWith

See Also	TFindReplaceDialog::TData

Syntax

char* ReplaceWith;

Description

ReplaceWith contains the replacement string.


See Also

TEditSearch::SearchData

TFindReplaceDialog::Data


TFloatingFrame Class

OWL Hierarchy	Inheritance

Header File

floatfra.h

Description

Derived from TFrameWindow and TTinyCaption, TFloatingFrame implements a floating frame that can be positioned anywhere in the parent window. Except for the addition of a tiny caption bar, the default behavior of TFrameWindow and TFloatingFrame is the same. Therefore, an application that uses TFrameWindow can easily gain the functionality of TFloatingFrame by just changing the name of the class to TFloatingFrame.

If there is a client window, the floating frame shrinks to fit the client window, leaving room for margins on the top, bottom, left, and right of the frame. Because the floating frame expects the client window to paint its own background, it does nothing in response to a WM_ERASEBKGND message. However, if there is no client window, the floating frame erases the client area background using COLOR_BTNFACE.

See PAINT.CPP, the sample program on your distribution disk, for an example of a floating frame.

Public Constructor

TFloatingFrame(TWindow *owner, char *title = 0, TWindow* clientWnd = 0, bool shrinkToClient = false, int CaptionHeight = DefaultCaptionHeight, bool popupPalette = false, Module* module = 0);

Public Member Functions

void SetMargins(const TSize& margin);

Protected Member Functions

TEventStatus DoNCHitTest(TPoint& screenPt, uint& evRes);

Response Table Entries

EV_ macros and member functions


TFloatingFrame Public Constructor

See Also	TFloatingFrame

Syntax

TFloatingFrame(TWindow *owner, char *title = 0, TWindow* clientWnd = 0, bool shrinkToClient = false, int CaptionHeight = DefaultCaptionHeight, bool popupPalette = false, Module* module = 0);

Description

Constructs a TFloatingFrame object attached to the specified parent window. By default, the floating frame window doesn't shrink to fit the client window, and the floating palette style isn't enabled.

Set popupPalette to true if you want to enable a floating palette style for the window. The floating palette is a popup window with a tiny caption, a standard window border, and a close box instead of a system menu box. There are no maximize or minimize buttons. A one pixel border is added around the client area in case a toolbox is implemented. This style must be turned on before the window is created. After the window is created, its style can't be changed.


See Also

TFrameWindow::TFrameWindow

TTinyCaption::TTinyCaption


TFloatingFrame::SetMargins
TFloatingFrame::DoNCHitTest

TFloatingFrame

Syntax

TEventStatus  DoNCHitTest(TPoint& screenPt, uint& evRes);

Description

If the floating palette is not enabled, returns esPartial. Otherwise, sends a message to the floating palette that the mouse or the cursor has moved, and returns esComplete.


TFloatingFrame::DoNCHitTest
TFloatingFrame::SetMargins

See Also	TFloatingFrame

Syntax

void SetMargins(const TSize& margin);

Description

Sets the margins of the floating palette window to the size specified in margin and sets the height of the tiny caption bar.


See Also

TTinyCaption::EnableTinyCaption


TFloatingFrame::Response Table Entries

TFloatingFrame

Response table entry	Member function

EV_WM_SYSCOMMAND	EvSysCommand

EV_WM_NCCALCSIZE	EvNCCalcSize

EV_WM_NCPAINT	EvNCPaint

EV_WM_NCHITTEST	EvNcHitTest


TFont Class

OWL Hierarchy	Inheritance

Header File

gdiobjec.h

Description

TFont derived from TGdiObject provides constructors for creating font objects from explicit information or indirectly.

Public Constructors

TFont(HFONT handle, TAutoDelete autoDelete = NoAutoDelete);

TFont(const char far* facename = 0, int height = 0, int width = 0, int escapement = 0, int orientation = 0, int weight = FW_NORMAL, uint8 pitchAndFamily = DEFAULT_PITCH|FF_DONTCARE, uint8 italic = false, uint8 underline = false, uint8 strikeout = false, uint8 charSet = 1, uint8 outputPrecision = OUT_DEFAULT_PRECIS, uint8 clipPrecision = CLIP_DEFAULT_PRECIS, uint8 quality = DEFAULT_QUALITY);

TFont(int height, int width, int escapement = 0, int orientation = 0, int weight = FW_NORMAL, uint8 italic = false, uint8 underline = false, uint8 strikeout = false, uint8 charSet = 1, uint8 outputPrecision = OUT_DEFAULT_PRECIS, uint8 clipPrecision = CLIP_DEFAULT_PRECIS, uint8 quality = DEFAULT_QUALITY uint8 pitchAndFamily = DEFAULT_PITCH|FF_DONTCARE, const char far* facename = 0);

TFont(const LOGFONT far* logFont);

TFont(const TFont& font);

Public Member Functions

bool GetObject(LOGFONT far& logFont) const;

operator HFONT() const;


TFont Public Constructors

See Also	TFont

Form 1

TFont(HFONT handle, TAutoDelete autoDelete = NoAutoDelete);

Form 2

TFont(const char far* facename = 0, int height = 0, int width = 0, int escapement = 0, int orientation = 0 int weight = FW_NORMAL, uint8 pitchAndFamily = DEFAULT_PITCH|FF_DONTCARE, uint8 italic = false, uint8 underline = false, uint8 strikeout = false, uint8 charSet = 1, uint8 outputPrecision = OUT_DEFAULT_PRECIS, uint8 clipPrecision = CLIP_DEFAULT_PRECIS, uint8 quality = DEFAULT_QUALITY);

Form 3

TFont(int height, int width, int escapement = 0, int orientation = 0, int weight = FW_NORMAL, uint8 italic = false, BYTE underline = false, uint8 strikeout = false, uint8 charSet = 1, uint8 outputPrecision = OUT_DEFAULT_PRECIS, uint8 clipPrecision = CLIP_DEFAULT_PRECIS, uint8 quality = DEFAULT_QUALITY uint8 pitchAndFamily = DEFAULT_PITCH|FF_DONTCARE, const char far* facename = 0);

Form 4

TFont(const LOGFONT far* logFont);

Form 5

TFont(const TFont& font);

Description

Form 1: Creates a TFont object and sets the Handle data member to the given borrowed handle. The ShouldDelete data member defaults to false, ensuring that the borrowed handle will not be deleted when the C++ object is destroyed.

Form 2: Creates a TFont object with the given values.

Form 3: Creates a TFont object with the given values. The constructor parameter list and default values match the Windows API CreateFont call.

Form 4: Creates a TFont object from the given logFont.

Form 5: The TFont copy constructor.


See Also

::CreateFont (Windows API)

::CreateFontIndirect (Windows API)

TGdiObject::Handle

TGdiObject::ShouldDelete


TFont::GetObject

See Also	TFont

Syntax

bool GetObject(LOGFONT far& logFont) const;

Description

Retrieves information about this pen object and places it in the given LOGFONT structure. Returns true if successful and false if unsuccessful.


See Also

TGdiObject::GetObject

LOGFONT struct


TFont::operator HFONT()

TFont

Syntax

operator HFONT() const;

Description

Typecasting operator that converts this font's Handle to type HFONT (the data type representing the handle to a physical font).


TFrameWindow Class

OWL Hierarchy	Inheritance

Header File

framewin.h

Description

Derived from TWindow, TFrameWindow controls such window-specific behavior as keyboard navigation and command processing for client windows. For example, when a window is reactivated, TFrameWindow is responsible for restoring a window's input focus and for adding menu bar and icon support. TFrameWindow is a streamable class.

In terms of window areas, the frame area consists of the border, system menus, toolbars and status bars whereas the client area excludes these areas. Although frame windows can support a client window, the frame window remains separate from the client window so that you can change the client window without affecting the frame window.

ObjectWindows uses this frame and client structure for both TFrameWindow and TMDIChild classes. Both these classes can hold a client class. Having a separate class for the client area of the window adds more flexibility to your program. For example, this separate client area, which might be a dialog box, can be moved into another frame window, either a main window or an MDI child window.

See TFloatingFrame for a description of a floating frame with the same default functionality as a frame window.

Public Data Members

bool KeyboardHandling;

Public Constructors and Destructors

TFrameWindow(TWindow* Parent, const char far* title = 0, TWindow* clientWnd = 0, bool shrinkToClient = false, TModule* module = 0);

TFrameWindow(HWND hWnd, TModule* module = 0);

~TFrameWindow();

Public Member Functions

virtual bool AssignMenu(TResId menuResId);

void EnableKBHandler();

virtual TWindow* GetClientWindow();

virtual HWND GetCommandTarget();

const TMenuDescr* GetMenuDescr();

bool HoldFocusHWnd(HWND hWndLose, HWND hWndGain);

void IdleAction(long idleCount);

bool MergeMenu(const TMenuDescr& childMenuDescr);

bool PreProcessMsg(MSG& msg);

bool RestoreMenu();

virtual TWindow* SetClientWindow(TWindow* clientWnd);

bool SetDocTitle(const char far* docname, int index);

bool SetIcon(TModule* iconModule, TResId iconResId);

virtual bool SetMenu(HMENU newMenu);

void SetMenuDescr(const TMenuDescr& menuDescr);

Protected Data Members

TWindow* ClientWnd;

int DocTitleIndex;

HWND HWndRestoreFocus;

TModule* MergeModule;

Protected Constructor

TFrameWindow();

Protected Member Functions

LRESULT EvCommand(uint id, HWND hWndCtl, uint notifyCode);

void EvCommandEnable(TCommandEnabler& ce);

bool EvEraseBkgnd(HDC);

HANDLE EvInitMenuPopup(HMENU hPopupMenu, uint index, bool sysMenu);

void EvPaint();

void EvParentNotify(uint event, uint childHandleOrX, uint childIDOrY);

HANDLE EvQueryDragIcon();

void EvSetFocus(HWND hWndLostFocus);

void EvSize(uint sizeType, TSize& size);

void Init(TWindow* clientWnd, bool shrinkToClient);

void SetupWindow();

Response Table Entries

EV macros and member functions


TFrameWindow::KeyboardHandling

TFrameWindow

Syntax

bool KeyboardHandling;

Description

Indicates if keyboard navigation is required.


TFrameWindow Public Constructors and Destructor

See Also	TFrameWindow

Form 1

TFrameWindow(TWindow* parent, const char far *title = 0, TWindow* clientWnd = 0, bool shrinkToClient = false, TModule* module = 0);

Form 2

TFrameWindow(HWND hWnd, TModule* module = 0);

Form 3

~TFrameWindow();

Description

Form 1: Constructs a window object with the parent window supplied in parent, which is zero if this is the main window. title, which by default is zero, contains the title displayed in the window's caption bar. clientWnd is the client window for this frame window or zero if none exists. shrinkToClient controls whether the client window will size to fit the frame or the frame window will fit the client. Note that this parameter only affects the size of the main window. When a client window is used in a frame window that doesn't have shrinktoClient set, the client window resizes to fit the frame window. When a client window is used in a frame window that has the shrinktoClient set, the frame window shrinks to fit the size of the client window.

Form 2: Constructor for a TFrameWindow that is being used as an alias for a non-ObjectWindows window. hWnd is the handle to the existing window object that TFrameWindow controls; module contains the module passed to the base class's contructor.

Destructor

Deletes any associated menu descriptor.


See Also

TWindow::TWindow

TFloatingFrame::TFloatingFrame


TFrameWindow::AssignMenu

See Also	TFrameWindow

Syntax

virtual bool AssignMenu(TResId menuResId);

Description

Sets Attr.Menu to the supplied menuResId and frees any previous strings pointed to by Attr.Menu. If HWindow is nonzero, loads and sets the menu of the window, destroying any previously existing menu.


See Also

TMDIFrameWindow::SetMenu

TFrameWindow::SetMenuDescr


TFrameWindow::EnableKBHandler

TFrameWindow

Syntax

void EnableKBHandler();

Description

Sets a flag indicating that the receiver has requested keyboard navigation (translation of keyboard input into control selections). By default, the keyboard interface, which lets users use the tab and arrow keys to move between the controls, is disabled for windows and dialog boxes.


TFrameWindow::GetClientWindow

See Also	TFrameWindow

Syntax

virtual TWindow* GetClientWindow();

Description

Returns a pointer to the client window. If you are trying to access a window-based object in a TMDIChild (which is a frame window), you can use this function.


See Also

TMDIChild


TFrameWindow::GetCommandTarget

TFrameWindow

Syntax

virtual HWND GetCommandTarget();

Description

Locates and returns the child window that is the target of the command and command enable messages. If the current application does not have focus or if the focus is within a toolbar in the application, GetCommandTarget returns the most recently active child window.

If an alternative form of command processing is desired, a user's main window class can override this function. TFrameWindow's EvCommand and EvCommandEnable  functions use GetCommandTarget to find the command target window. This member is not available under Presentation Manager.


TFrameWindow::GetMenuDescr

See Also	TFrameWindow

Syntax

const TMenuDescr* GetMenuDescr();

Description

Returns a pointer to the menu descriptor.


See Also

TFrameWindow::SetMenuDescr

TMenuDescr


TFrameWindow::HoldFocusHwnd

See Also	TFrameWindow

Syntax

bool HoldFocusHWnd(HWND hWndLose, HWND hWndGain);

Description

Overrides TWindow's virtual function. Responds to a request by a child window to hold its HWND when it is losing focus. Stores the child's HWND in HwndRestoreFocus.


See Also

TWindow::HoldFocusHwnd


TFrameWindow::IdleAction

See Also	TFrameWindow

Syntax

void IdleAction(long idleCount);

Description

Overrides TWindow's virtual function. TApplication calls the main window's IdleAction when no messages are waiting to be processed. TFrameWindow uses this idle time to perform command enabling for the menu bar. It also forwards IdleAction to each of its children. IdleAction can be overridden to do background processing.


See Also

TApplication::IdleAction


TFrameWindow::MergeMenu

See Also	TFrameWindow

Syntax

bool MergeMenu(const TMenuDescr& childMenuDescr);

Description

Merges the given menu descriptor with this frame's own menu descriptor and displays the resulting menu in this frame. See TMenuDescr for a description of menu bar types that can be merged.


See Also

TMenuDescr


TFrameWindow::PreProcessMsg

See Also	TFrameWindow

Syntax

bool PreProcessMsg(MSG& msg);

Description

Overrides TWindow's virtual function. Performs preprocessing of window messages. If the child window has requested keyboard navigation, PreProcessMsg handles any accelerator key messages and then processes any other keyboard messages.


See Also

TWindow::PreProcessMsg


TFrameWindow::RestoreMenu

TFrameWindow

Syntax

bool RestoreMenu();

Description

Restores the default menu of the frame window.


TFrameWindow::SetClientWindow

TFrameWindow

Syntax

virtual TWindow* SetClientWindow(TWindow* clientWnd);

Description

Sets the client window to the specified window. Users are responsible for destroying the old client window if they want to eliminate it.


TFrameWindow::SetDocTitle

TFrameWindow

Syntax

bool SetDocTitle(const char far* docname, int index);

Description

Overrides TWindow's virtual function. Pastes the number of the view into the caption and then shows the number on the screen. This function can be overridden if you don't want to use the default implementation, which displays a number on the screen. That is, you might want to write "Two" instead of ":2" on the screen. For an example of the behavior of this function, see step 12 of the ObjectWindows tutorial, which renumbers the views if one of them is closed.


TFrameWindow::SetIcon

See Also	TFrameWindow

Syntax

bool SetIcon(TModule* iconModule, TResId iconResId);

Description

Sets the icon in the module specified in iconModule to the resource ID specified in iconResId.  See the sample file bmpview.cpp for an example of painting an icon from a bitmap. You can set the iconResId to one of these pre-defined values as well as user-defined values:

IDI_APPLICATION	Default icon used for applications

IDI_ASTERISK	Asterisk used for an informative message

IDI_EXCLAMATION	Exclamation mark used for a warning message

IDI_HAND	Hand used for warning messages

IDI_QUESTION	Question mark used for prompting a response


See Also

TFrameWindow::EvQueryDragIcon


TFrameWindow::SetMenu

TFrameWindow

Syntax

virtualBOOL SetMenu(HMENU newMenu);

Description

Overrides TWindow's non-virtual SetMenu function, thus allowing derived classes the opportunity to implement this function differently from TWindow. SetMenu sets the window's menu to the menu indicated by newMenu. If newMenu is 0, the window's current menu is removed. SetMenu returns 0 if the menu remains unchanged; otherwise, it returns a nonzero value.


TFrameWindow::SetMenuDescr

See Also	TFrameWindow

Syntax

void SetMenuDescr(const TMenuDescr& menuDescr);

Description

Sets the menu descriptor to the new menu descriptor.


See Also

TFrameWindow::GetMenuDescr

TMenuDescr


TFrameWindow::ClientWnd

TFrameWindow

Syntax

TWindow* ClientWnd;

Description

ClientWnd points to the frame's client window.


TFrameWindow::DocTitleIndex

TFrameWindow

Syntax

int DocTitleIndex;

Description

Holds the index number for the document title.


TFrameWindow::HWndRestoreFocus

See Also	TFrameWindow

Syntax

HWND HWndRestoreFocus;

Description

Stores the handle of the child window whose focus gets restored.


See Also

TFrameWindow::HoldFocusHwnd


TFrameWindow::MergeModule

TFrameWindow

Syntax

TModule* MergeModule;

Description

Tells the frame window which module the menu comes from. TDecoratedFrame uses this member to get the menu hints it displays at the bottom of the screen. It assumes that the menu hints come from the same place the menu came from.


TFrameWindow Protected Constructors and Destructor
TFrameWindow Protected Constructor

TFrameWindow

Syntax

TFrameWindow();

Description

Protected constructor used in conjunction with Init function for initializing virtually derived classes.


TFrameWindow::EvCommand

TFrameWindow

Syntax

LRESULT EvCommand(uint id, HWND hWndCtl, uint notifyCode);

Description

Provides extra processing for commands and lets the focus window and its parent windows handle the command first.


TFrameWindow::EvCommandEnable

See Also	TFrameWindow

Syntax

void EvCommandEnable(TCommandEnabler& ce);

Description

Handles checking and unchecking of the frame window's menu items. EvCommandEnable uses TWindow's RouteCommandEnable member function to perform the majority of this command enabling work.


See Also

TWindow::RouteCommandEnable


TFrameWindow::EvEraseBkgnd

TFrameWindow

Syntax

bool EvEraseBkgnd(HDC);

Description

EvEraseBkgnd erases the background of the window specified in HDC. It returns true if the background is erased; otherwise, it returns false.


TFrameWindow::EvInitMenuPopup

TFrameWindow

Syntax

HANDLE EvInitMenuPopup(HMENU hPopupMenu, uint index, bool sysMenu);

Description

Sent before a pop-up menu is displayed, EvInitMenuPopup lets an application change the items on the menu before the menu is displayed. EvInitMenuPopup controls whether the items on the pop-up menu are enabled or disabled, checked or unchecked, or strings. HMENU indicates the menu handle. index is the index of the pop-up menu. sysMenu indicates if the pop-up menu is the system menu.


TFrameWindow::EvPaint

See Also	TFrameWindow

Syntax

void EvPaint();

Description

Responds to a WM_PAINT message in the client window in order to paint the iconic window's icon or to allow client windows a change to paint the icon.


See Also

TWindow::Paint

TScroller::BeginView

TScroller::EndView


TFrameWindow::EvParentNotify

TFrameWindow

Syntax

void EvParentNotify(uint event, uint childHandleOrX, uint childIDOrY);

Description

Responds to a message to notify the parent window that a given event has occurred. If the client window is destroyed, closes the parent window. If shrinkToClient is set and the child window has changed size, the frame is adjusted.

When a TFrameWindow's client window is destroyed, the TFrameWindow object sees the WM_PARENTNOTIFY message and posts a close message to itself. Without this message, an empty frame would remain and the client window would then have to determine how to destroy the frame. If you don't want this to happen, you can derive from the frame window and have your application handle the EvParentNotify or EvClose messages.


TFrameWindow::EvQueryDragIcon

See Also	TFrameWindow

Syntax

HANDLE EvQueryDragIcon();

Description

Responds to a WM_QUERYDRAGICON message sent to a minimized (iconic) window that is going to be dragged. Instead of the default icon, EvQueryDragIcon uses the icon that was set using SetIcon.

This member is not available under Presentation Manager.


See Also

TFrameWindow::SetIcon


TFrameWindow::EvSetFocus

TFrameWindow

Syntax

void EvSetFocus(HWND hWndLostFocus);

Description

Restores the focus to the active window. hWndLostFocus contains the handle for the window that lost focus.


TFrameWindow::EvSize

See Also	TFrameWindow

Syntax

void EvSize(uint sizeType, TSize& size);

Description

Resizes the client window's size so that it is equivalent to the client rectangle's size. Calls TWindow::EvSize) in response to an incoming WM_SIZE message.


See Also

TSize


TFrameWindow::Init

TFrameWindow

Syntax

void Init (TWindow* clientWnd, bool shrinkToClient);

Description

This initialize function is for use with virtually derived classes, which must call Init before construction is completed. This procedure provides necessary data to virtually derived classes and takes care of providing the data in the appropriate sequence.


TFrameWindow::SetupWindow

See Also	TFrameWindow

Syntax

void SetupWindow();

Description

Calls TWindow::SetUpWindow to create windows in a child list. SetupWindow performs the initial adjustment of the client window if one exists, assigns the frame's menu based on the menu descriptor, and initializes HwndRestoreFocus.


See Also

TWindow::SetUpWindow


TFrameWindow Response Table Entries

TFrameWindow

Response table entry	Member function

EV_WM_ERASEBKGND	EvEraseBkgnd

EV_WM_INITMENUPOPUP	EvInitMenuPopup

EV_WM_PAINT	EvPaint

EV_WM_PARENTNOTIFY	EvParentNotify

EV_WM_QUERYDRAGICON	EvQueryDragIcon (Windows only)

EV_WM_SETFOCUS	EvSetFocus

EV_WM_SIZE	EvSize


TGadget Class

OWL Hierarchy	Inheritance

Header File

gadget.h

Description

TGadget is the base class for the following derived gadget classes:

Class	Description

TBitmapGadget	Displays a bitmap

TButtonGadget	Uses a bitmap to simulate a button gadget

TControlGadget	Encapsulates inserting a control such as an edit control or a combobox, into a gadget window.

TTextGadget	Displays text

TSeparatorGadget	Separates logical groups of gadgets.

TGadget interface objects belong to a gadget window, have borders and margins, and have their own coordinate system. The margins are the same as those for TGadgetWindow and borders are always measured in border units.

To set the attributes for the gadget, you can either choose a border style (which automatically sets the individual border edges) or set the borders and then override the member function PaintBorder to create a custom look for your gadget. If you change the borders, margins, or border style, the gadget window's GadgetChangedSize member function is invoked.

Although, by default, gadgets shrink-wrap to fit around their contents, you can control this attribute by setting your own values for ShrinkWrapWidth and ShrinkWrapHeight.

A gadget window, being an actual window, receives messages from the mouse. After the gadget window receives the message, it decides which gadget should receive the message by calling the member function directly instead of sending or posting a message.

Public Data Members

bool Clip;

bool WideAsPossible;

Public enums and structures

struct TBorders

enum TBorderStyle{None, Plain, Raised, Recessed, Embossed};

struct TMargins

Public Constructors and Destructor

TGadget(int id = 0, TBorderStyle = None);

virtual ~TGadget();

Public Member Functions

virtual void CommandEnable();

TBorders& GetBorders();

TBorderStyle GetBorderStyle();

TRect& GetBounds();

virtual void GetDesiredSize(TSize& size);

bool GetEnabled();

int GetId();

TMargins& GetMargins();

void GetOuterSizes(int& left, int& right, int& top, int& bottom);

TGadget* NextGadget();

void SetBorders(TBorders& borders);

void SetBorderStyle(TBorderStyle);

virtual void SetBounds(TRect& rect);

virtual void SetEnabled(bool);

void SetMargins(TMargins& margins);

void SetShrinkWrap(bool shrinkWrapWidth, bool shrinkWrapHeight);

void SetSize(TSize& size);

virtual void SysColorChange();

Protected Data Members

TRect Bounds;

TBorders Borders;

int Id;

TMargins Margins;

bool ShrinkWrapHeight;

bool ShrinkWrapWidth;

bool TrackMouse;

TGadgetWindow* Window;

Protected member functions

void GetInnerRect(TRect& rect);

virtual void Inserted();

void Invalidate(bool erase = true);

void InvalidateRect(const TRect& rect, bool erase = true);

virtual void LButtonDown(uint modKeys, TPoint& point);

virtual void LButtonUp(uint modKeys, TPoint& point);

virtual void MouseEnter(uint modKeys, TPoint& point);

virtual void MouseLeave(uint modKeys, TPoint& point);

virtual void MouseMove(uint modKeys, TPoint& point);

virtual void Paint(TDC&);

virtual void PaintBorder(TDC& dc);

virtual bool PtIn(TPoint& point);

virtual void Removed();

void Update();


TGadget::Clip

TGadget

Syntax

bool Clip;

Description

If Clip is false, clipping borders have not been established. If Clip is true, the drawing for each gadget is restrained by the gadget's border.


TGadget::TBorders struct

TGadget

Syntax

struct TBorders

   unsigned  Left;

   unsigned  Right;

   unsigned  Top;

   unsigned  Bottom;

Description

Holds the values for the left, right, top, and bottom measurements of the gadget.


TGadget::TBorderStyle enum

TGadget

Syntax

enum TBorderStyle {None, Plain, Raised, Recessed, Embossed};

Description

Enumerates an exclusive list of border styles: None, Plain, Raised (the gadget appears to be raised above the gadget window), Recessed (the gadget appears to be recessed into the gadget window), or Embossed (the gadget appears to have an embossed border). For an example of border styles, see the sample ObjectWindows program, MDIFILE.CPP, on your distribution disk.


TGadget::TMargins struct

See Also	OWL Hierarchy	TGadget

Syntax

struct TMargins {

   enum TUnits {Pixels, LayoutUnits, BorderUnits};

   TUnits  Units;

   int  Left;

   int  Right;

   int  Top;

   int  Bottom;

Description

Used by the TGadgetWindow and TGadget classes, TMargins contains the measurements of the margins for the gadget. The constructor initializes Units to LayoutUnits and sets Left, Right, Top, and Bottom equal to 0.


See Also

TGadgetWindow::SetMargins


TGadget::WideAsPossible

See Also	TGadget

Syntax

bool WideAsPossible;

Description

Initially set to false, WideAsPossible indicates whether the gadget width will be adjusted by the gadget window to be as wide as possible in the remaining space.


See Also

TGadgetWindow::WideAsPossible


TGadget Public Constructor and Destructor
TGadget Public Constructors and Destructor

TGadget

Constructor

TGadget(int id = 0, TBorderStyle = None);

Description

Constructs a TGadget object with the specified ID and border style.

Destructor

virtual ~TGadget();

Description

Destroys a TGadget interface object and removes it from its associated window.


TGadget::CommandEnable

*TGadget

Syntax

virtual void CommandEnable();

Description

Provided so that the gadget can perform command enabling (so it can handle an incoming message if it's appropriate to do so).


TGadget::GetBorders

See Also	TGadget

Syntax

TBorders& GetBorders();

Description

Gets the gadget's borders measured in border units that are based on SM_CXBORDER and SM_CYBORDER.


See Also

TGadget::SetBorders


TGadget::GetBorderStyle

See Also	TGadget

Syntax

TBorderStyle GetBorderStyle();

Description

Gets the style for the gadget's borders.


See Also

TGadget::SetBorderStyle


TGadget::GetBounds

See Also	TGadget

Syntax

TRect& GetBounds();

Description

Returns the boundary rectangle for the gadget.


See Also

TButtonGadget::SetNotchCorners


TGadget::GetDesiredSize

TGadget

Syntax

virtual void GetDesiredSize(TSize& size);

Description

Determines how big the gadget can be. The gadget window sends this message to query the gadget's size. If shrink-wrapping is requested, GetDesiredSize returns the size needed to accommodate the borders and margins. If shrink-wrapping is not requested, it returns the gadget's current width and height. TGadgetWindow needs this information to determine how big the gadget needs to be, but it can adjust these dimensions if necessary. If WideAsPossible is true, then the width parameter (size.cx) is ignored.


TGadget::GetEnabled

See Also	TGadget

Syntax

bool GetEnabled();

Description

Determines whether keyboard and mouse input have been enabled for the specified gadget. If the gadget is enabled, GetEnabled returns true; otherwise, it returns false. By default, keyboard and mouse input are enabled.


See Also

TGadget::SetEnabled


TGadget::GetId

TGadget

Syntax

int GetId();

Description

Gets the ID for the gadget.


TGadget::GetMargins

TGadget

Syntax

TMargins& GetMargins();

Description

Gets the margin dimensions.


TGadget::GetOuterSizes

TGadget

Syntax

void GetOuterSizes(int& left, int& right, int& top, int& bottom);

Description

Returns the amount of space (in pixels) taken up by the borders and margins.


TGadget::NextGadget

TGadget

Syntax

TGadget* NextGadget();

Description

Returns the next gadget in the list of gadgets.


TGadget::SetBorders

See Also	TGadget

Syntax

void SetBorders(TBorders& borders);

Description

Sets the borders for the gadget. If the borders are changed, SetBorders calls TGadgetWindow::GadgetChangedSize to notify the gadget window of the change.


See Also

TGadget::GetBorders


TGadget::SetBorderStyle

See Also	TGadget

Syntax

void SetBorderStyle(TBorderStyle);

Description

Sets the border style for the gadget.


See Also

TGadget::GetBorderStyle

TGadget::TBorderStyle


TGadget::SetBounds

TGadget

Syntax

virtual void SetBounds(TRect& rect);

Description

Informs the gadget of a change in its bounding rectangle. Although the default behavior updates only the instance variable Bounds, you can override this method to also update the internal state of the gadget.


TGadget::SetEnabled

See Also	TGadget

Syntax

virtual void SetEnabled(bool);

Description

Enables or disables keyboard and mouse input for the gadget. By default, the gadget is disabled when it is created and must be enabled before it can be activated.


See Also

TGadget::GetEnabled


TGadget::SetMargins

See Also	TGadget

Syntax

void SetMargins(TMargins& margins);

Description

Sets the margins of the gadget. If the margins are changed, SetMargins calls TGadgetWindow::GadgetChangedSize to notify the gadget window.


See Also

TGadget::GetMargins


TGadget::SetShrinkWrap

TGadget

Syntax

void SetShrinkWrap(bool shrinkWrapWidth, bool shrinkWrapHeight);

Description

Sets the ShrinkWrapWidth and ShrinkWrapHeight data members. Your derived class can call TGadgetWindow::GadgetChangedSize if you want to change the size of the gadget.


TGadget::SetSize

TGadget

Syntax

void SetSize(TSize& size);

Description

Alters the size of the gadget and then calls TGadgetWindow::GadgetChangedSize for the size change to take effect.

This function is needed only if you have turned off shrink-wrapping in one or both dimensions; otherwise, use the GetDesiredSize member function to return the shrink-wrapped size.


TGadget::SysColorChange

TGadget

Syntax

virtual void SysColorChange();

Description

Called when the system colors have been changed so that gadgets can rebuild and repaint, if necessary.


TGadget::Bounds

See Also	TGadget

Syntax

TRect Bounds;

Description

Contains the bounding rectangle for the gadget in gadget window coordinates.


See Also

TGadget::GetInnerRect


TGadget::BorderStyle

TGadget

Syntax

TBorderStyle BorderStyle;

Description

Contains the border style for the gadget.


TGadget::Borders

TGadget

Syntax

TBorders Borders;

Description

Contains the border measurements of TGadget::GetInnerRect.


TGadget::Id

TGadget

Syntax

int Id;

Description

Contains the gadget's ID.


TGadget::Margins

See Also	TGadget

Syntax

TMargins Margins;

Description

Contains the margin measurements of the rectangle or the gadget.


See Also

TGadget::GetInnerRect


TGadget::ShrinkWrapHeight

TGadget

Syntax

bool ShrinkWrapHeight;

Description

Indicates if the gadget is to be shrink-wrapped to fit around its contents.


TGadget::ShrinkWrapWidth

TGadget

Syntax

bool ShrinkWrapWidth;

Description

Indicates if the gadget is to be shrink-wrapped to fit around its contents.


TGadget::TrackMouse

TGadget

Syntax

bool TrackMouse;

Description

Initialized to false. When TrackMouse is true, the gadget captures  the mouse on LButtonDown by calling TGadgetWindow's GadgetSetCapture and releases the mouse on  LButtonUp by calling GadgetReleaseCapture.


TGadget::Window

TGadget

Syntax

TGadgetWindow* Window;

Description

References the owning or parent window for the gadget.


TGadget::GetInnerRect

TGadget

Syntax

void GetInnerRect(TRect& rect);

Description

Computes the area of the gadget's rectangle excluding the borders and margins.


TGadget::Inserted

TGadget

Syntax

virtual void Inserted();

Description

Called after a gadget is inserted into a window.


TGadget::Invalidate

TGadget

Syntax

void Invalidate(bool erase = true);

Description

Used to invalidate the active (usually nonborder) portion of the gadget, Invalidate calls InvalidateRect and passes the boundary width and height of the area to erase.


TGadget::InvalidateRect

TGadget

Syntax

void InvalidateRect(const TRect& rect, bool erase = true);

Description

Invalidates the gadget-relative rectangle in the parent window.


TGadget::LButtonDown

TGadget

Syntax

virtual void LButtonDown(uint modKeys, TPoint& point);

Description

Captures the mouse if TrackMouse is set. point is located in the gadget's coordinate system.


TGadget::LButtonUp

TGadget

Syntax

virtual void LButtonUp(uint modKeys, TPoint& point);

Description

Releases the mouse capture if TrackMouse is set. point is located in the gadget's coordinate system.


TGadget::MouseEnter

See Also	TGadget

Syntax

virtual void MouseEnter(uint modKeys, TPoint& point);

Description

Called when the mouse enters the gadget.


See Also

TGadget::MouseLeave


TGadget::MouseLeave

See Also	TGadget

Syntax

virtual void MouseLeave(uint modKeys, TPoint& point);

Description

Called when the mouse leaves the gadget.


See Also

TGadget::MouseEnter


TGadget::MouseMove

See Also	TGadget

Syntax

virtual void MouseMove(uint modKeys, TPoint& point);

Description

If mouse events are captured, MouseMove responds to a mouse dragging message. point is located in the receiver's coordinate system.


See Also

TGadget::MouseEnter

TGadget::MouseLeave


TGadget::Paint

TGadget

Syntax

virtual void Paint(TDC&);

Description

Calls PaintBorder to paint the indicated device context.


See Also

TTextGadget::Paint


TGadget::PaintBorder

TGadget

Syntax

virtual void PaintBorder(TDC& dc);

Description

Used to paint the border, PaintBorder determines the width and height of the gadget and uses the color returned by GetSyscolor to paint or highlight the area with the specified brush. Depending on whether the border style is raised, embossed, or recessed, PaintBorder paints the specified boundary. You can override this function if you want to implement a border style that is not supported by ObjectWindows' gadgets.


TGadget::PtIn

TGadget

Syntax

virtual bool PtIn(TPoint& point);

Description

Determines if the point is within the receiver's bounding rectangle and returns true if this is the case; otherwise, returns false.


TGadget::Removed

TGadget

Syntax

virtual void Removed();

Description

Called after a gadget is removed from a window.


TGadget::Update

TGadget

Syntax

void Update();

Description

Repaints the gadget if possible.


TGadgetWindowFont Class

See Also	OWL Hierarchy	Inheritance

Header File

gadgetwi.h

Description

Derived from TFont, TGadgetWindowFont is a specific font used in gadget windows for sizing and default text. You can specify the point size of the font (not the size in pixels) and whether it is bold or italic. You can use one of the following FF_xxxx constants to indicate the font family type:

Value	Meaning

FF_DECORATIVE	Specialty fonts such as Old English.

FF_DONTCARE	The font type does not matter.

FF_MODERN	Fonts such as Pica, Elite or Courier with a constant stroke, width, and with or without serifs.

FF_ROMAN	Fonts such as Times New Roman and New Century Schoolbook with varied stroke and with serifs.

FF_SCRIPT	Fonts such as Script that are designed to resemble handwriting.

FF_SWISS	Fonts such as MS Sans Serif with variable stroke width and without serifs.

Depending on the typeface, the font weight can be one of the following FW_xxxx constants:

Value	Meaning

FW_DONTCARE	Does not matter

FW_THIN	Thin

FW_EXTRALIGHT	Extra light

FW_ULTRALIGHT	Extra light

FW_LIGHT	Light

FW_NORMAL	Normal

FW_REGULAR	Normal font weight

FW_MEDIUM	Medium

FW_SEMIBOLD	Somewhat bold

FW_DEMIBOLD	Somewhat bold

FW_BOLD	Bold

FW_EXTRABOLD	Extra bold

FW_ULTRABOLD	Extra bold

FW_BLACK	Heavy weight

FW_HEAVY	Heavy weight

Because the font's appearance depends on the typeface, some fonts have only FW_NORMAL, FW_REGULAR, and FW_BOLD available. If FW_DONTCARE is indicated, the default font weight is used.

Public Constructor

TGadgetWindowFont(int pointSize = 10, bool bold = false, bool italic = false);


See Also

TFont


TGadgetWindowFont Public Constructor

See Also	TGadgetWindowFont

Syntax

TGadgetWindowFont(int pointSize = 10, bool bold = false, bool italic = false);

Description

Constructs a TGadgetWindowFont interface object with a default point size of 10 picas without bold or italic typeface. By default, the constructor creates the system font: a variable-width, sans-serif Helvetica.


See Also

TFont


TGadgetWindow Class

OWL Hierarchy	Inheritance

Header File

gadgetwi.h

Description

Derived from TWindow, TGadgetWindow maintains a list of tiled gadgets for a window and lets you dynamically arrange tool bars. You can specify the following attributes of these gadgets:

Horizontal or vertical tiling. Positions the gadgets horizontally or vertically within the inner rectangle (the area excluding borders and margins).

Gadget font. Default font to use for gadgets and for calculating layout units. For font information, see the description of TGadgetWindowFont.

Left, right, top, and bottom margins. Specified in pixels, layout units (based on the window font), or border units (the width or height of a thin window border).

Measurement units. Specified in pixels, layout units, or border units.

Gadget window size. A gadget window can shrink-wrap its width, height, or both to fit around its gadgets. By default, horizontally tiled gadgets shrink-wrap to fit the height of the window and vertically tiled gadgets shrink-wrap to fit the width of the window.

TGadgetWindow is the base class for the following derived classes: TControlBar, TMessageBar, TToolBox, and TStatusBar.

Public Constructor and Destructor

TGadgetWindow(TWindow* parent = 0, TTileDirection direction = Horizontal, TFont *font = new TGadgetWindowFont, TModule* module = 0);

~TGadgetWindow();

Type Definitions

enum THintMode{NoHints, PressHints, EnterHints};

Public member functions

TGadget* FirstGadget() const;

void GadgetChangedSize(TGadget& gadget);

TGadget* GadgetFromPoint(TPoint& point);

void GadgetReleaseCapture(TGadget& gadget);

bool GadgetSetCapture(TGadget& gadget);

TGadget* GadgetWithId(int id) const;

TTileDirection GetDirection() const;

TFont& GetFont();

uint GetFontHeight() const;

THintMode GetHintMode();

void IdleAction();

virtual void Insert(TGadget& gadget, TPlacement = After, TGadget *sibling = 0);

virtual void LayoutSession();

TGadget* NextGadget(TGadget& gadget) const;

virtual TGadget* Remove(TGadget& gadget);

virtual void SetDirection(TTileDirection direction);

void SetHintCommand(int id);

void SetHintMode(THintMode hintMode);

void SetMargins(TMargins& margins);

void SetShrinkWrap(bool shrinkWrapWidth, bool shrinkWrapHeight);

Protected data members

TGadget* AtMouse;

TBrush* BkgndBrush;

TGadget* Capture;

TTileDirection Direction;

bool DirtyLayout;

TFont* Font;

uint FontHeight;

TGadget* Gadgets;

THintMode HintMode;

TMargins Margins;

uint NumGadgets;

bool ShrinkWrapHeight;

bool ShrinkWrapWidth;

uint WideAsPossible;

Protected member functions

bool Create();

void EvLButtonDown(uint modKeys, TPoint& point);

void EvLButtonUp(uint modKeys, TPoint& point);

void EvMouseMove(uint modKeys, TPoint& point);

void EvSize(uint sizeType, TSize& size);

void EvSysColorChange();

virtual void GetDesiredSize(TSize& size);

virtual void GetInnerRect(TRect& rect);

void GetMargins(TMargins& margins, int& left, int& right, int& top, int& bottom);

int LayoutUnitsToPixels(int units);

void Paint(TDC& dc, bool erase, TRect& rect);

virtual void PaintGadgets(TDC& dc, bool erase, TRect& rect);

virtual void PositionGadget(TGadget* previous, TGadget* next, TPoint& point);

virtual void TileGadgets();

Response Table Entries

EV_ macros and member functions


TGadgetWindow Public constructors and destructor

TGadgetWindow

Constructor

TGadgetWindow(TWindow* parent = 0, TTileDirection direction = Horizontal, TFont *font = new TGadgetWindowFont, TModule* module = 0);

Destructor

~TGadgetWindow();

Description

Creates a TGadgetWindow interface object with the default tile direction and font and passes module with a default value of 0.

Destructor

Destructs the TGadgetWindow object by deleting all of its gadgets and fonts.


THintMode enum

See Also	TGroupBox

Header File

gadgetwi.h

Syntax

enum THintMode{NoHints, PressHints, EnterHints};

Description

Enumerates the hint mode settings of the gadget--either no hints, hints when a button is pressed, or hints when the mouse passes over a gadget.


See Also

TGadgetWindow::GetHintMode


TGadgetWindow::FirstGadget

See Also	TGadgetWindow

Syntax

TGadget* FirstGadget() const;

Description

Returns the FirstGadget in the list.


See Also

TGadgetWindow::FirstGadget


TGadgetWindow::GadgetChangedSize

See Also	TGadgetWindow

Syntax

void GadgetChangedSize(TGadget& gadget);

Description

Used to notify the gadget window that a gadget has changed its size, GadgetChangedSize calls LayoutSession to re-layout all gadgets.


See Also

TGadget::SetShrinkWrap

TGadgetWindow::GadgetChangedSize


TGadgetWindow::GadgetFromPoint

TGadgetWindow

Syntax

TGadget* GadgetFromPoint(TPoint& point);

Description

Returns the gadget at the given window coordinates.


TGadgetWindow::GadgetReleaseCapture

See Also	TGadgetWindow

Syntax

void GadgetReleaseCapture(TGadget& gadget);

Description

Releases the capture so that other windows can receive mouse messages.


See Also

TGadgetWindow::GadgetSetCapture


TGadgetWindow::GadgetSetCapture

See Also	TGadgetWindow

Syntax

bool GadgetSetCapture(TGadget& gadget);

Description

GadgetSetCapture reserves all mouse messages for the gadget window until the capture is released. Although gadgets are always notified if a left button-down event occurs within the rectangle, the derived gadget class must call GadgetSetCapture if you want the gadget to be notified when a mouse drag and a mouse button-up event occurs.


See Also

TGadgetWindow::GadgetReleaseCapture


TGadgetWindow::GadgetWithId

TGadgetWindow

Syntax

TGadget* GadgetWithId(int id) const;

Description

Returns a pointer to the gadget associated with the given ID (id).


TGadgetWindow::GetDirection

See Also	TGadgetWindow

Syntax

TTileDirection GetDirection() const;

Description

Gets the horizontal or vertical orientation of the gadgets.


See Also

TGadgetWindow::SetDirection


TGadgetWindow::GetFont

See Also	TGadgetWindow

Syntax

TFont& GetFont();

Description

Returns the font (which is  Sans Serif by default).


See Also

TGadgetWindowFont::TGadgetWindowFont


TGadgetWindow::GetFontHeight

TGadgetWindow

Syntax

uint GetFontHeight() const;

Description

Gets the height of the window's font.


TGadgetWindow::GetHintMode

TGadgetWindow

Syntax

THintMode GetHintMode();

Description

Returns the hint mode.


TGadgetWindow::IdleAction

See Also	TGadgetWindow

Syntax

void IdleAction();

Description

While no messages are waiting to be processed, IdleAction is called and iterates through the gadgets, invoking their CommandEnable member function.


See Also

TGadget::CommandEnable


TGadgetWindow::Insert

See Also	TGadgetWindow

Syntax

virtual void Insert(TGadget& gadget, TPlacement = After, TGadget *sibling = 0);

Description

Inserts a gadget before or after a sibling gadget (TPlacement). If sibling is 0, then the new gadget is inserted at either the beginning or the end of the gadget list. If this window has already been created, LayoutSession needs to be called after inserting gadgets.


See Also

TGadgetWindow::LayoutSession

TGadgetWindow::Remove


TGadgetWindow::LayoutSession

See Also	TGadgetWindow

Syntax

virtual void LayoutSession();

Description

LayoutSession is typically called when a change occurs in the size of the margins or gadgets or when gadgets are added or deleted. LayoutSession calls TileGadgets to tile the gadgets in the specified direction and Invalidate to mark the area as invalid (needs repainting).


See Also

TGadgetWindow::Insert

TGadgetWindow::Remove

TWindow::Invalidate


TGadgetWindow::NextGadget

TGadgetWindow

Syntax

TGadget* NextGadget(TGadget& gadget) const;

Description

Returns the next gadget after gadget or 0 if none exists.


TGadgetWindow::Remove

See Also	TGadgetWindow

Syntax

virtual TGadget* Remove(TGadget& gadget);

Description

Removes a gadget from the gadget window. The gadget is returned but not destroyed. Remove returns 0 if the gadget is not in the window.

If this window has already been created, the calling application must call LayoutSession after any gadgets have been removed.


See Also

TGadgetWindow::Insert

TGadgetWindow::LayoutSession


TGadgetWindow::SetDirection

See Also	TGadgetWindow

Syntax

virtual void SetDirection(TTileDirection direction);

Description

Sets the horizontal or vertical orientation of the gadgets. If the gadget window is already created, SetDirection readjusts the dimensions of the gadget window to fit around the gadgets.

The setting of the direction parameter is also related to the setting of the second parameter (Tlocation) in TDecoratedFrame's Insert function,. which specifies where the decoration is added in relation to the frame window's client window. If the second parameter in TDecoratedFrame::Insert is set to top or bottom, the direction parameter in SetDirection must be horizontal. If the second parameter in TDecoratedFrame::Insert is set to left or right, the direction parameter in SetDirection must be vertical.


See Also

TGadgetWindow::GetDirection


TGadgetWindow::SetHintCommand

See Also	TGadgetWindow

Syntax

void SetHintCommand(int id);

Description

Simulates menu selection messages so that ObjectWindows command processing can display command hints for the given command id (CM_xxxx).


See Also

CM_xxxx edit constants

CM_xxxx edit file constants


TGadgetWindow::SetHintMode

See Also	TGadgetWindow

Syntax

void SetHintMode(THintMode hintMode);

Description

Sets the mode of the hint text. Defaults to PressHints (displays hint text when a button is pressed).


See Also

THintMode enum


TGadgetWindow::SetMargins

See Also	TGadgetWindow

Syntax

void SetMargins(TMargins& margins);

Description

Sets or changes the margins for the gadget window and calls LayoutSession.


See Also

TGadgetWindow::Margins


TGadgetWindow::SetShrinkWrap

TGadgetWindow

Syntax

void SetShrinkWrap(bool shrinkWrapWidth, bool shrinkWrapHeight);

Description

Sets the width and height of the data members. By default, if the tile direction is horizontal, ShrinkWrapWidth is false and ShrinkWrapHeight is true. Also by default, if the direction is vertical, ShrinkWrapWidth is true and ShrinkWrapHeight is false.


TGadgetWindow::AtMouse

TGadgetWindow

Syntax

TGadget* AtMouse;

Description

The last gadget at the mouse position.


TGadgetWindow::BkgndBrush

TGadgetWindow

Syntax

TBrush* BkgndBrush;

Description

The color of the background brush.


TGadgetWindow::Capture

See Also	TGadgetWindow

Syntax

TGadget* Capture;

Description

Points to the gadget that currently has the mouse capture; otherwise, if no gadget has the mouse capture, Capture is 0.


See Also

TGadgetWindow::GadgetSetCapture


TGadgetWindow::Direction

TGadgetWindow

Syntax

TTileDirection Direction;

Description

The direction of the tiling--either horizontal or vertical.


TGadgetWindow::DirtyLayout

See Also	TGadgetWindow

Syntax

bool DirtyLayout;

Description

Indicates the layout has changed and gadgets need to be re-tiled. Using DirtyLayout avoids redundant tiling when gadget windows are created.


See Also

TGadgetWindow::LayoutSession


TGadgetWindow::Font

See Also	TGadgetWindow

Syntax

TFont* Font;

Description

Points to the font used to calculate layout units.


See Also

TGadgetWindow::GetFont


TGadgetWindow::FontHeight

See Also	TGadgetWindow

Syntax

uint FontHeight;

Description

Holds the height of the gadget window's font.


See Also

TGadgetWindow::GetFont


TGadgetWindow::Gadgets

TGadgetWindow

Syntax

TGadget* Gadgets;

Description

Points to the first gadget in the gadget list.


TGadgetWindow::HintMode

See Also	TGadgetWindow

Syntax

THintMode HintMode;

Description

Holds the hint text mode.


See Also

THintMode enum


TGadgetWindow::Margins

See Also	TGadgetWindow

Syntax

TMargins Margins;

Description

Holds the margin values for the gadget window.


See Also

TGadgetWindow::SetMargins


TGadgetWindow::NumGadgets

TGadgetWindow

Syntax

uint NumGadgets;

Description

The number of gadgets in the window.


TGadgetWindow::ShrinkWrapHeight

See Also	TGadgetWindow

Syntax

bool ShrinkWrapHeight;

Description

If ShrinkWrapHeight is true, the window will shrink its width to fit the tallest gadget for horizontally tiled gadgets.


See Also

TGadgetWindow::SetShrinkWrap


TGadgetWindow::ShrinkWrapWidth

See Also	TGadgetWindow

Syntax

bool ShrinkWrapWidth;

Description

If ShrinkWrapWidth is true, the window will shrink its width to fit the widest gadget for vertically tiled gadgets.


See Also

TGadgetWindow::SetShrinkWrap


TGadgetWindow::WideAsPossible

TGadgetWindow

Syntax

uint WideAsPossible;

Description

The number of gadgets that are as wide as possible.


TGadgetWindow::Create

See Also	TGadgetWindow

Syntax

bool Create();

Description

Overrides TWindow member function and chooses the initial size of the gadget if shrink-wrapping was requested.


See Also

TGadgetWindow::SetShrinkWrap


TGadgetWindow::EvLButtonDown

TGadgetWindow

Syntax

void EvLButtonDown(uint modKeys, TPoint& point);

Description

Responds to a left button-down mouse message by forwarding the event to the gadget positioned under the mouse.


TGadgetWindow::EvLButtonUp

TGadgetWindow

Syntax

void EvLButtonUp(uint modKeys, TPoint& point);

Description

Responds to a left button-up mouse message by forwarding the event to the gadget that has the capture.


TGadgetWindow::EvMouseMove

TGadgetWindow

Syntax

void EvMouseMove(uint modKeys, TPoint& point);

Description

If mouse events are captured, EvMouseMove responds to a mouse move message by forwarding the event to the gadget that has the capture.


TGadgetWindow::EvSize

TGadgetWindow

Syntax

void EvSize(uint sizeType, TSize& size);

Description

Calls TWindow::EvSize to perform any default processing. If DirtyLayout true and WideAsPossible is greater than 0, EvSize sets DirtyLayout to true and calls TileGadgets to readjust the size and Invalidate to mark the area for redrawing.


TGadgetWindow::EvSysColorChange

TGadgetWindow

Syntax

void EvSysColorChange();

Description

EvSysColorChange, which is called when any system colors have changed, forwards the event to all gadgets.


TGadgetWindow::GetDesiredSize

See Also	TGadgetWindow

Syntax

virtual void GetDesiredSize(TSize& size);

Description

If shrink-wrapping was requested, GetDesiredSize returns the size needed to accommodate the borders and the margins of the widest and highest gadget; otherwise, it returns the width and height in the window's Attr structure.

If you want to leave extra room for a specific look (for example, a separator line between gadgets, a raised line, and so on), you can override this function. However, if you override GetDesiredSize, you will probably also need to override GetInnerRect to calculate your custom inner rectangle.


See Also

TGadgetWindow::GetInnerRect


TGadgetWindow::GetInnerRect

See Also	TGadgetWindow

Syntax

virtual void GetInnerRect(TRect& rect);

Description

GetInnerRect computes the rectangle inside of the borders and margins of the gadget.

If you want to leave extra room for a specific look (for example, a separator line between gadgets, a raised line, and so on), you can override this function. If you override GetInnerRect, you will probably also need to override GetDesiredSize to calculate your custom total size.


See Also

TGadgetWindow::GetDesiredSize


TGadgetWindow::GetMargins

TGadgetWindow

Syntax

void GetMargins(TMargins& margins, int& left, int& right, int& top, int& bottom);

Description

Returns the left, right, top, and bottom margins in pixels.


TGadgetWindow::LayoutUnitsToPixels

See Also	TGadgetWindow

Syntax

int LayoutUnitsToPixels(int units);

Description

Converts layout units to pixels. A layout unit is determined by dividing the window font height by eight.


See Also

TGadgetWindow::LayoutSession


TGadgetWindow::Paint

See Also	TGadgetWindow

Syntax

void Paint(TDC& dc, bool erase, TRect& rect);

Description

Puts the font into the device context and calls PaintGadgets.


See Also

TGadgetWindow::PaintGadgets


TGadgetWindow::PaintGadgets

TGadgetWindow

Syntax

virtual void PaintGadgets(TDC& dc, bool erase, TRect& rect);

Description

Called by Paint to repaint all of the gadgets, PaintGadgets iterates through the list of gadgets, determines the gadget's area, and repaints each gadget.

You can override this function to implement a specific look (for example, separator line, raised, and so on).


TGadgetWindow::PositionGadget

See Also	TGadgetWindow

Syntax

virtual void PositionGadget(TGadget* previous, TGadget* next, TPoint& point);

Description

PositionGadget is called to allow spacing adjustments to be made before each gadget is positioned.


See Also

TGadgetWindow::TileGadgets


TGadgetWindow::TileGadgets

See Also	TGadgetWindow

Syntax

virtual void TileGadgets();

Description

Tiles the gadgets in the direction requested (horizontal or vertical).

Calls PositionGadget to give derived classes an opportunity to adjust the spacing between gadgets in their windows.


See Also

TGadgetWindow::PositionGadget


TGadgetWindow Response table entries

TGadgetWindow

Response table entry	Member function

EV_WM_LBUTTONDOWN	EvLButtonDown

EV_WM_LBUTTONUP	EvLButtonUp

EV_WM_MOUSEMOVE	EvMouseMove

EV_WM_SIZE	EvSize

EV_WM_SYSCOLORCHANGE	EvSysColorChange


TGauge Class

OWL Hierarchy	Inheritance

Header File

gauge.h

Description

A streamable class derived from TControl, TGauge defines the basic behavior of gauge controls. Gauges are display-only horizontal or vertical controls that provide duration or analog information about a particular process. A typical use of a gauge occurs in installation programs where a control provides a graphical display indicating the percentage of files copied. In general, horizontal gauges with a broken (dashed-line) bar are used to display short-duration, process information, and horizontal gauges with a solid bar are used to illustrate long-duration, process information. Usually, vertical gauges are preferred for displaying analog information.

Public Constructor

TGauge(TWindow* parent, const char far* title, int id, int X, int Y, int W, int H, bool isHorizontal = true, int margin = 0, TModule* module = 0);

Public Member Functions

void GetRange(int& min, int& max) const;

int GetValue() const;

void SetColor(TColor color);

void SetLed(int spacing, int thick = 90);

void SetRange(int min, int max);

void SetValue(int value);

Protected Data Members

TColor BarColor;

int IsHorizontal;

int LedSpacing;

int LedThick;

int Margin;

int Max;

int Min;

int Value;

Protected Member Functions

bool EvEraseBkgnd(HDC);

void Paint(TDC& dc, bool erase, TRect& rect);

virtual void PaintBorder(TDC& dc);

Response Table Entries

EV_ macros and member functions


TGauge Public Constructor
TGauge Public Constructors

TGauge

Constructor

TGauge(TWindow* parent, const char far* title, int id, int X, int Y, int W, int H, bool isHorizontal = true, int margin = 0, TModule* module = 0);

Description

Constructs a TGauge object with borders that are determined by using the value of SM_CXBORDER. Sets IsHorizontal to isHorizontal. Sets border thickness and spacing between dashed borders (LEDs) to 0. Sets the range of possible values from 0 to 100.


TGauge::GetRange

TGauge

Syntax

void GetRange(int& min, int& max) const;

Description

Gets the minimum and maximum values for the gauge.


TGauge::GetValue

TGauge

Syntax

int GetValue() const;

Description

Returns the current value of the gauge.


TGauge::SetColor

TGauge

Syntax

void SetColor(TColor color);

Description

Sets the BarColor data member to the value specified in color.


TGauge::SetLed

TGauge

Syntax

void SetLed(int spacing, int thick = 90);

Description

Sets the LedSpacing and LedThick data members to the values spacing and thick.


TGauge::SetRange

TGauge

Syntax

void SetRange(int min, int max);

Description

Sets the Min and Max data members to min and max values returned by the constructor. If Max is less than or equal to Min, SetRange resets Max to Min + 1.


TGauge::SetValue

TGauge

Syntax

void SetValue(int value);

Description

Restricts value to be within the minimum and maximum values established for the gauge. If the current value has changed, SetValue marks the old position for repainting. Then, it sets the data member Value to the new value.


TGauge::BarColor

TGauge

Syntax

TColor BarColor;

Description

Holds the bar or LED color, which defaults to blue.


TGauge::IsHorizontal

TGauge

Syntax

int IsHorizontal;

Description

Set to the isHorizontal argument of the constructor. IsHorizontal is true if the gauge is horizontal and false if it is vertical.


TGauge::LedSpacing

TGauge

Syntax

int LedSpacing;

Description

Holds the integer value (in gauge units) of the spacing between the broken bars of the gauge. Note that TGauge does not paint the title while using LED spacing.


TGauge::LedThick

TGauge

Syntax

int LedThick;

Description

Holds the thickness of the broken bar.


TGauge::Max

TGauge

Syntax

int Max;

Description

Holds the maximum value (in gauge units) displayed on the gauge.


TGauge::Min

TGauge

Syntax

int Min;

Description

Holds the minimum value (in gauge units) displayed on the gauge.


TGauge::Margin

TGauge

Syntax

int Margin;

Description

Contains the border width and height of the gauge.


TGauge::Value

TGauge

Syntax

int Value;

Description

Holds the current value of the gauge.


TGauge::EvEraseBkgnd

TGauge

Syntax

bool EvEraseBkgnd(HDC);

Description

Overrides the TWindow::EvEraseBkgnd function and erases the background of the gauge. Whenever the background is repainted, EvEraseBkgnd is called to avoid flickering.


TGauge::Paint

See Also	TGauge

Syntax

void Paint(TDC& dc, bool erase, TRect& rect);

Description

Overrides TWindow::Paint and paints the area and the border of the gauge. Uses the values supplied in rect and dc to paint the given rectangle on the given device context. Uses the values in LedSpacing and IsHorizontal to draw a horizontal or vertical gauge with solid or broken bars.


See Also

TDC

TRect


TGauge::PaintBorder

TGauge

Syntax

virtual void PaintBorder(TDC& dc);

Description

Paints the gauge border using the specified device context. Depending on whether the border style is raised, embossed, or recessed, PaintBorder paints the specified boundary. You can override this function if you want to implement a border style that is not supported by ObjectWindows' gauges.


TGauge Response Table Entries

TGauge

Response table entry	Member function

EV_WM_ERASEBKGND	EvEraseBkgnd


TGdiObject Class

OWL Hierarchy	Inheritance

Header File

gdiobjec.h

Description

GdiObject is the root, pseudo-abstract base class for ObjectWindows' GDI (Graphics Device Interface) wrappers. The TGdiOject-based classes let you work with a GDI handle and construct a C++ object with an aliased handle. Some GDI objects are also based on TGdiObject for handle management. Generally, the TGdiObject-based class hierarchy handles all GDI objects apart from the DC (Device Context) objects handled by the TDC-based tree.

The five DC selectable classes (TPen, TBrush, TFont, TPalette, and TBitmap), and the TIcon, TCursor, TDib, and TRegion classes, are all derived directly from TGdiObject.

TGdiObject maintains the GDI handle and a ShouldDelete flag that determines if and when the handle and object should be destroyed. Protected constructors are provided for use by the derived classes: one for borrowed handles, and one for normal use.

An optional orphan control mechanism is provided. By default, orphan control is active, but you can turn it off by defining the NO_GDI_ORPHAN_CONTROL identifier:

#define NO_GDI_ORPHAN_CONTROL

With orphan control active, the following static member functions are available:

RefAdd, RefCount, RefDec, RefFind, RefInc, and RefRemove.

These maintain object reference counts and allow safe orphan recovery and deletion. Macros, such as OBJ_REF_ADD, let you deactivate or activate your orphan control code by simply defining or undefining NO_GDI_ORPHAN_CONTROL. When NO_GDI_ORPHAN_CONTROL is undefined, for example, OBJ_REF_ADD(handle, type) expands to TGdiObject::RefAdd((handle),(type)), but when NO_GDI_ORPHAN_CONTROL is defined, the macro expands to handle.

Public Destructor

~TGdiObject();

Public Enums

enum TAutoDelete{NoAutoDelete, AutoDelete};

enum TType{None, Pen, Brush, Font, Palette, Bitmap, TextBrush};

Public Member Functions

int GetObject(int count, void far* object) const;

static void RefAdd(HANDLE handle, TType type);

static int RefCount(HANDLE handle);

static void RefDec(HANDLE handle);

static void RefDec(HANDLE handle, bool wantDelete);

static TObjInfo* RefFind(HANDLE object);

static void RefInc(HANDLE handle);

static void RefRemove(HANDLE handle);

operator HGDIOBJ()const

Protected Data Members

HANDLE Handle;

bool ShouldDelete;

Protected Member Functions

void CheckValid(uint resId=IDS_GDIFAILURE)

static void CheckValid(HANDLE handle, uint resId=IDS_GDIFAILURE)

Protected Constructors

TGdiObject();

TGdiObject(HANDLE handle, TAutoDelete autoDelete = NoAutoDelete);

Macros

OBJ_REF_ADD(handle, type)

OBJ_REF_COUNT(handle)

OBJ_REF_DEC(handle, wantDelete)

OBJ_REF_INC(handle)

OBJ_REF_REMOVE(handle)


TGdiObject::Public Destructor
TGdiObject Public Destructor

TGdiObject

Syntax

~TGdiObject();

Description

If ShouldDelete is false no action is taken. Otherwise with ShouldDelete true, the action of the destructor depends on whether orphan control is active or not. If orphan control is inactive (that is, if NO_ORPHAN_CONTROL is defined) ~TGdiObject deletes the GDI object. If orphan control is active (the default) the object is deleted only if the its reference count is 0.


TGdiObject::enum TAutoDelete

TGdiObject

Syntax

enum TAutoDelete{NoAutoDelete, AutoDelete};

Description

This enum, which is defined in the private base class, gdibase.h, enumerates the flag values for GDI Handle constructors. This flag is used to control GDI object deletion in the destructors.


TGdiObject::enum TType

See Also	TGdiObject

Syntax

enum TType{None, Pen, Brush, Font, Palette, Bitmap, TextBrush};

Description

This enumeration is used to store the object type in the struct TObjInfo. This internal structure is used to track object reference counts during debugging sessions.


See Also

TGdiObject::RefCount


TGdiObject::GetObject

See Also	TGdiObject

Syntax

int GetObject(int count, void far* object) const;

Description

Obtains information about this GDI object and places it in the object buffer. If the call succeeds and object is not 0, GetObject returns the number of bytes copied to the object buffer. If the call succeeds and object is 0, GetObject returns the number of bytes needed in the object buffer for the type of object being queried. Depending on what type of GDI object is derived, this function retrieves a LOGPEN, LOGBRUSH, LOGFONT, or BITMAP structure through object.


See Also

TPen::GetObject

BITMAP struct

LOGBRUSH struct

LOGFONT struct

LOGPEN struct


TGdiObject::RefAdd

See Also	TGdiObject

Syntax

static void RefAdd(HANDLE handle, TType type);

Description

Available only if orphan control is active (that is, if NO_GDI_ORPHAN_CONTROL is undefined). RefAdd adds a reference entry for the object with the given handle and type to the ObjInfoBag table and sets the reference count to 1. If the table already has a matching entry, no action is taken.


See Also

TGdiObject::RefCount

macro OBJ_REF_ADD


TGdiObject::RefCount

See Also	TGdiObject

Syntax

static int RefCount(HANDLE handle);

Description

Available only if orphan control is active, that is, if NO_GDI_ORPHAN_CONTROL is undefined. RefCount returns this object's current reference count or -1 if the object is not in the ObjInfoBag table.


See Also

macro OBJ_REF_COUNT


TGdiObject::RefDec

See Also	TGdiObject

Syntax

static void RefDec(HANDLE handle);

static void RefDec(HANDLE handle, bool wantDelete);

Description

Available only if orphan control is active, that is, if NO_GDI_ORPHAN_CONTROL is undefined. RefDec decrements this object's reference count by 1 and deletes the object when the reference count reaches zero. A warning is issued if the deletion was supposed to happen but didn't. Likewise, a warning is issued if the deletion wasn't supposed to happen but did. The deleted object is also detached from the ObjInfoBag table.

The second version of RefDec is available only if the _ _TRACE identifier is defined. You can vary the normal deletion strategy by setting wantDelete to true or false.


See Also

TGdiObject::RefCount

macro OBJ_REF_DEC


TGdiObject::RefFind

See Also	TGdiObject

Syntax

static TObjInfo* RefFind(HANDLE object);

Description

Available only if orphan control is active (that is, if NO_GDI_ORPHAN the given object is undefined). If found, the object's type and reference count are returned in the specified TObjInfo object. RefFind returns 0 if no match is found.


See Also

TGdiObject::RefCount


TGdiObject::RefInc

See Also	TGdiObject

Syntax

static void RefInc(HANDLE handle);

Description

Available only if orphan control is active (that is, if NO_GDI_ORPHAN_CONTROL is undefined). RefInc increments by 1 the reference count of the object associated with handle.


See Also

TGdiObject::RefCount

macro OBJ_REF_INC


TGdiObject::RefRemove

See Also	TGdiObject

Syntax

static void RefRemove(HANDLE handle);

Description

Available only if orphan control is active (that is, if NO_GDI_ORPHAN_CONTROL is undefined). RefRemove removes the reference entry to the object with the given handle from the ObjInfoBag table. If the given handle is not found, no action is taken.


See Also

TGdiObject::RefCount

macro OBJ_REF_REMOVE


TGdiObject::operator HGDIOBJ

TGdiObject

Syntax

operator HGDIOBJ() const

Description

Type casting operator that converts this GDI object handle to type HGDIOBJ.


TGdiObject::Handle

See Also	TGdiObject

Syntax

HANDLE Handle;

Description

The GDI handle of this object.


See Also

TGdiObject Protected Constructors


TGdiObject::CheckValid

TGdiObject

Form 1

void CheckValid( uint resId=IDS_GDIFAILURE)

Form 2

static void CheckValid( HANDLE handle, uint resId=IDS_GDIFAILURE)

Description

Both versions of CheckValid check for a valid GDI object handle. If one is not found a GDI exception is thrown for the given resource id.


TGdiObject::ShouldDelete

See Also	TGdiObject

Syntax

bool ShouldDelete;

Description

Set true if the Destructor needs to delete this object's GDI handle.


See Also

TGdiObject Protected Constructors


TGdiObject Protected Constructors

See Also	TGdiObject

Form 1

TGdiObject();

Form 2

TGdiObject(HANDLE handle, TAutoDelete autoDelete = NoAutoDelete);

Description

Form 1: This default constructor sets Handle to 0 and ShouldDelete to true. This constructor is intended for use by derived classes that must set the Handle member.

Form 2: This constructor is intended for use by derived classes only. The Handle data member is "borrowed" from an existing handle given by the argument handle The ShouldDelete data member defaults to false ensuring that the borrowed handle will not be deleted when the object is destroyed.


See Also

TGdiObject::enumTAutoDelete

TGdiObject::Handle

TGdiObject::RefCount

TGdiObject::ShouldDelete


TGdiObject::OBJ_REF_ADD

See Also	TGdiObject

Syntax

OBJ_REF_ADD(handle, type)

Description

If orphan control is active (the default), OBJ_REF_ADD(handle, type) is defined as TGdiObject::RefAdd((handle), (type)). The latter adds to the ObjInfoBag table a reference entry for the object with the given handle and type, and sets its count to 1. If orphan control is inactive, OBJ_REF_ADD(handle) is defined as handle. This macro lets you write orphan control code that can be easily deactivated with the single statement #define NO_GDI_ORPHAN_CONTROL.


See Also

TGdiObject::RefAdd


TGdiObject::OBJ_REF_COUNT

See Also	TGdiObject

Syntax

OBJ_REF_COUNT(handle)

Description

If orphan control is active (the default), OBJ_REF_COUNT(handle) is defined as TGdiObject::RefCount((handle)). The latter returns the reference count of the object with the given handle, or -1 if no such object exists. If orphan control is inactive, OBJ_REF_COUNT(handle) is defined as -1. This macro lets you write orphan control code that can be easily deactivated with the single statement #define NO_GDI_ORPHAN_CONTROL.


See Also

TGdiObject::RefCount


TGdiObject::OBJ_REF_DEC

See Also	TGdiObject

Syntax

OBJ_REF_DEC(handle, wantDelete)

Description

If orphan control is active (the default), OBJ_REF_DEC(handle, wantDelete) is defined as either TGdiObject::RefDec((handle)) or TGdiObject::RefDec((handle), (wantDelete)). The latter format occurs only if _ _TRACE is defined. RefDec(handle) decrements the reference count of the object associated with handle and optionally deletes orphans or warns you of their existence. If orphan control is inactive, OBJ_REF_DEC(handle) is defined as handle. This macro lets you write orphan control code that can be easily deactivated with the single statement #define NO_GDI_ORPHAN_CONTROL.


See Also

TGdiObject::RefDec


TGdiObject::OBJ_REF_INC

See Also	TGdiObject

Syntax

OBJ_REF_INC(handle)

Description

If orphan control is active (the default), OBJ_REF_INC(handle) is defined as TGdiObject::RefInc((handle)). The latter increments the reference count of the object associated with handle. If orphan control is inactive, OBJ_REF_DEC(handle) is defined as handle. This macro lets you write orphan control code that can be easily deactivated with the single statement #define NO_GDI_ORPHAN_CONTROL.


See Also

TGdiObject::RefInc


TGdiObject::OBJ_REF_REMOVE

See Also	TGdiObject

Syntax

OBJ_REF_REMOVE(handle)

Description

If orphan control is active (the default), OBJ_REF_REMOVE(handle) is defined as TGdiObject::RefRemove((handle)). The latter removes from the ObjInfoBag table the reference entry for the object associated with handle. If orphan control is inactive, OBJ_REF_REMOVE(handle) is defined as handle. This macro lets you write orphan control code that can be easily deactivated with the single statement #define NO_GDI_ORPHAN_CONTROL.


See Also

TGdiObject::RefRemove


TGdiBase::TXGdi Class

OWL Hierarchy	Inheritance

Header File

gdibase.h

Description

Describes an exception resulting from GDI failures such as creating too many TWindow device contexts (DCs). This exception occurs, for example, if a DC driver cannot be located or if a device-independent bitmap (DIB) file cannot be read.

The following code from the PAINT.CPP sample program on your distribution disk throws a TXGdi exception if a new DIB cannot be created.

void TCanvas::NewDib(int width, int height, int nColors)

{

  TDib* dib;

  try {

    dib = new TDib(width, height, nColors);

  }

  catch (TGdiBase::TXGdi& x) {

    MessageBox("Could Not Create DIB", GetApplication()->Name,   MB_OK);

    return;

}

Public Constructor

TXGdi(uint resId = IDS_GDIFAILURE, HANDLE = 0);

Public Member Functions

TXOwl* Clone();

static string Msg(uint resId, HANDLE);

void Throw();


TGdiBase::TXGdi Public Constructor

TGdiBase::TXGdi

Syntax

TXGdi(uint resId = IDS_GDIFAILURE, HANDLE = 0);

Description

Constructs a TXGdi object with a default IDS_GDIFAILURE message.


TGdiBase::Clone
TGdiBase::TXGdi::Clone

TGdiBase::TXGdi

Syntax

TXOwl* Clone();

Description

Makes a copy of the exception object. Clone must be implemented in any class derived from TXOwl.


TGdiBase::Msg
TGdiBase::TXGdi::Msg

TGdiBase::TXGdi

Syntax

static string Msg(uint resId, HANDLE);

Description

Converts the resource ID to a string and returns the string message.


TGdiBase::Throw
TGdiBase::TXGdi::Throw

TGdiBase::TXGdi

Syntax

void Throw();

Description

Throws the exception object. Throw must be implemented in any class derived from TXOwl.


TGroupBox Class

OWL Hierarchy	Inheritance

Header File

groupbox.h

Description

An instance of a TGroupBox is an interface object that represents a corresponding group box element. Generally, TGroupBox objects are not used in dialog boxes or dialog windows (TDialog), but are used when you want to create a group box in a window.

Although group boxes do not serve an active purpose onscreen, they visually unify a group of selection boxes such as check boxes and radio buttons or other controls. Behind the scenes, however, they can take an important role in handling state changes for their group of controls (normally check boxes or radio buttons).

For example, you might want to respond to a selection change in any one of a group of radio buttons in a similar manner. You can do this by deriving a class from TGroupBox that redefines the member function SelectionChanged.

Alternatively, you could respond to selection changes in the group of radio buttons by defining a response for the group box's parent. To do so, define a child-ID-based response member function using the ID of the group box. The group box will automatically send a child-ID-based message to its parent whenever the radio button selection state changes. This class is streamable.

Public Data Members

bool NotifyParent()t;

Public constructors

TGroupBox(TWindow* Parent, int Id, const char far *text, int x, int y, int w, int h, TModule* module = 0);

TGroupBox(TWindow* Parent, int resourceId, TModule* module = 0);

Public Member Functions

char far* GetClassName();

virtual void SelectionChanged(int controlId);


TGroupBox::NotifyParent

TGroupBox

Syntax

bool NotifyParent;

Description

Flag that indicates whether parent is to be notified when the state of the group box's selection boxes has changed. NotifyParent is true by default.


TGroupBox Public Constructors
TGroupBox::Public constructors

See Also	TGroupBox

Syntax 1

TGroupBox(TWindow* parent, int Id, const char far *text, int x, int y, int w, int h, TModule* module = 0);

Description

Constructs a group box object with the supplied parent window (Parent), control ID (Id), associated text (text), position (x, y) relative to the origin of the parent window's client area, width (w), and height (h). Invokes the TControl constructor with similar parameters, then modifies Attr.Style, adding BS_GROUPBOX and removing WS_TABSTOP. NotifyParent is set to true; by default, the group box's parent is notified when a selection change occurs in any of the group box's controls.

Syntax 2

TGroupBox(TWindow* parent int resourceId, TModule* module = 0);

Description

Constructs a TGroupBox object to be associated with a group box control of a TDialog. object. Invokes the TControl constructor with identical parameters. resourceID must correspond to a group box resource that you define.


See Also

TControl::TControl

TWindow::DisableTransfer


TGroupBox::SelectionChanged

TGroupBox

Form 1

virtual void SelectionChanged(int controlId);

Description

If NotifyParent is true, SelectionChanged notifies the parent window of the group box that one of its selections has changed by sending it a child-ID-based message. This member function can be redefined to allow the group box to handle selection changes in its group of controls.


TGroupBox::GetClassName

TGroupBox

Syntax

char far* GetClassName();

Description

GetClassName returns the name of TGroupBox's Windows registration class, "BUTTON" If Borland Windows Custom Controls (BWCC) is enabled, GetClassName returns BUTTON_CLASS.


THatch8x8Brush Class

See Also	OWL Hierarchy

Header File

gdiobjec.h

Description

Derived from TBrush, THatch8x8Brush defines a small, 8x8, monochrome, configurable hatch brush. Because the hatch brush is a logical brush created from device-independent bitmaps (DIBs), it can be passed to any device context (DC), which then renders the brush into the appropriate form for the device.

Although the default brush color is a white foreground and a black background, you can vary the colors of the hatched brush. The colors can be any one of the TColor object encapsulated colors, namely the standard RGB values.

THatch8x8Brush contains static arrays that define common hatched brush patterns. The hatched brush patterns you can select are

Standard

Forward diagonal

Backward diagonal

You can use THatch8x8Brush  to design a variety of hatched brush border patterns around a simple rectangle or an OLE container. You can also use THatch8x8Brush in conjunction with TUIHandle.

Public Data Members

const static uint8 Hatch11F1[8];

const static uint8 Hatch13B1[8];

const static uint8 Hatch13F1[8];

const static uint8 Hatch22B1[8];

const static uint8 Hatch22F1[8];

Public Constructor

THatch8x8Brush(const uint8 hatch[], TColor fgColor = TColor::White, TColor bgColor = TColor::Black);

Public Member Functions

void Reconstruct(const uint8 hatch[], TColor fgColor, TColor bgColor);


  A brush that fills an area with a pattern created from hatch marks.


See Also

TBrush

TColor

TUIHandle


THatch8x8Brush::Hatch11F1[8]

THatch8x8Brush

Syntax

const static uint8 Hatch11F1[8];

Description

The static array Hatch11F1[8] holds the logical hatched brush pattern of one pixel on and one pixel off in monochrome, offset one per row as the following pattern illustrates:


THatch8x8Brush::Hatch13B1[8]

THatch8x8Brush

Syntax

const static uint8 Hatch13B1[8];

Description

The static array Hatch13B1[8] holds a hatched brush pattern of one pixel on and three pixels off in backward diagonal hatch marks, offset one per row as the following pattern illustrates:


THatch8x8Brush::Hatch13F1[8]

THatch8x8Brush

Syntax

const static uint8 Hatch13F1[8];

Description

The static array Hatch13F1[8] holds a hatched brush pattern of one pixel on and three pixels off in forward diagonal hatch marks, offset one per row as the following pattern illustrates:


THatch8x8Brush::Hatch22B1[8]

THatch8x8Brush

Syntax

const static uint8 Hatch22B1[8];

Description

The static array Hatch22B1[8] holds a hatched brush pattern of two pixels on and two off in backward diagonal hatch marks, offset one per row as the following pattern illustrates:


THatch8x8Brush::Hatch22F1[8]

THatch8x8Brush

Syntax

const static uint8 Hatch22F1[8];

Description

The static array Hatch22F1[8] holds a monochrome hatched brush pattern of two pixels on and two off in forward diagonal hatch marks, offset one per row as the following pattern illustrates:


THatch8x8Brush Public Constructors

THatch8x8Brush

Syntax

THatch8x8Brush(const uint8 hatch[], TColor fgColor = TColor::White, TColor bgColor = TColor::Black);

Description

Constructs a THatchBrush object with the specified hatched pattern and colors. Although the hatched brush is, by default, white on a black background, you can control the displayed colors by passing different colors in the constructor, where fgColor represents the foreground color and bgColor represents the background color of a TColor object type.

Note that colors can be specified in either palette mode (a reference to a corresponding color palette entry in the currently realized palette) or RGB mode (an actual red, green, or blue color value).


THatch8x8Brush::Reconstruct

THatch8x8Brush

Syntax

void Reconstruct(const uint8 hatch[], TColor fgColor, TColor bgColor);

Description

Reconstructs the hatched brush with a new pattern or new set of colors.


TIC Class

OWL Hierarchy	Inheritance

Header File

dc.h

Description

Derived from TDC, TIC is a DC class that provides a constructor for creating a DC object from explicit driver, device, and port names.

Public Constructor

TIC(const char far* driver, const char far* device, const char far* output, const DEVMODE far* initData=0);


TIC Public Constructor

See Also	TIC

Syntax

TIC(const char far* driver, const char far* device, const char far* output, const DEVMODE far* initData=0);

Description

Creates a DC object with the given driver, device, and port names and initialization values.


See Also

TDC::GetDeviceCaps

DEVMODE struct


 TIcon Class

OWL Hierarchy	Inheritance

Header File

gdiobjec.h

Description

TIcon, derived from TGdiObject, represents the GDI object icon class. TIcon constructors can create icons from a resource or from explicit information. Because icons are not real GDI objects, the TIcon destructor overloads the base destructor, ~TGdiObject.

Public Constructors and Destructor

TIcon(HICON handle, TAutoDelete autoDelete = NoAutoDelete);

TIcon(HINSTANCE instance, const TIcon& icon);

TIcon(HINSTANCE instance, TResID resID);

TIcon(HINSTANCE instance, const char far* filename, int index);

TIcon(HINSTANCE instance, const TSize& size, int planes, int bitsPixel, const void far* andBits, const void far* xorBits);

TIcon(const void* resBits, uint32 resSize);

TIcon(const ICONINFO* iconInfo);

~TIcon();

Public Member Functions

bool GetIconInfo(ICONINFO* iconInfo) const;

operator HICON() const;


TIcon Public Constructors and Destructor

See Also	TIcon

Syntax

TIcon(HICON handle, TAutoDelete autoDelete = NoAutoDelete);

Description

Creates a TIcon object and sets the Handle data member to the given borrowed handle. The ShouldDelete data member defaults to false, ensuring that the borrowed handle will not be deleted when the C++ object is destroyed.

Syntax

TIcon(HINSTANCE instance, const TIcon& icon);

Description

Creates a copy of the given icon object.

Syntax

TIcon(HINSTANCE instance, TResID resID);

Description

Creates an icon object from the given resource.

Syntax

TIcon(HINSTANCE instance, const char far* filename, int index);

Description

Creates an icon object from the given resource file.

Syntax

TIcon(HINSTANCE instance, const TSize& size, int planes, int bitsPixel, const void far* andBits, const void far* xorBits);

Description

Creates an icon object with the given values.

Syntax

TIcon(const void* resBits, uint32 resSize);

Description

Creates an icon object of the given size from the bits found in the resBits buffer.

Syntax

TIcon(const ICONINFO* iconInfo);

Description

Creates an icon object with the given ICONINFO information.

Destructor Syntax

~TIcon();

Description

Destroys the icon and frees any memory that the icon occupied.


See Also

~TGdiObject

TGdiObject::Handle

TGdiObject::ShouldDelete,

TResID

TSize

ICONINFO structure


TIcon::GetIconInfo

See Also	TIcon

Syntax

 bool GetIconInfo(ICONINFO* iconInfo) const;

Description

Retrieves information about this icon and copies it into the given ICONINFO structure. Returns true if the call is successful; otherwise returns false.


See Also

ICONINFO structure


TIcon::operator HICON()

TIcon

Syntax

 operator HICON() const;

Description

Typecasting operator that converts this icon's Handle to type HICON (the data type representing the handle to an icon resource).


TInputDialog Class

OWL Hierarchy	Inheritance

Header File

inputdia.h

Description

Provides a generic dialog box to retrieve text input by a user. When the input dialog box is constructed, its title, prompt, and default input text are specified. TInputDialog is a streamable class.

Public Data Members

char far* buffer;

int BufferSize;

char far* prompt;

Public Constructor

TInputDialog(TWindow* parent, const char far *title, const char far *prompt, char far* buffer, int buffersize, TModule* module = 0, TValidator* valid = 0)

Public Member Function

void TransferData(TTransferDirection direction)

Protected Member Function

virtual void SetupWindow();


TInputDialog::buffer

TInputDialog

Syntax

char far* buffer;

Description

Pointer to the buffer that returns the text retrieved from the user. When passed to the constructor of the input dialog box, contains the default text to be initially displayed in the edit control.


TInputDialog::BufferSize

TInputDialog

Syntax

int BufferSize;

Description

Contains the size of the buffer that returns user input.


TInputDialog::prompt

TInputDialog

Syntax

char far* prompt;

Description

Points to the prompt for the input dialog box.


TInputDialog Public Constructor
TInputDialog Public Constructors

TInputDialog

Syntax

TInputDialog(TWindow* parent, const char far *title, const char far *prompt, char far* buffer, int buffersize, TModule* module = 0, TValidator* valid = 0)

Description

Invokes TDialog's constructor, passing it parent, the resource identifier, and module. Sets the caption of the dialog box to title and the prompt static control to prompt. Sets the Buffer and BufferSize data members to buffer and bufferSize.


TInputDialog::TransferData

TInputDialog

Syntax

void TransferData(TTransferDirection direction);

Description

Transfers the data of the input dialog box. If direction is tdSetData, sets the text of the static and edit controls of the dialog box to the text in prompt and buffer. If direction is tdGetData, fills the buffer with the current text of the Editor.


TInputDialog::SetupWindow

TInputDialog

Syntax

virtual void SetupWindow();

Description

Calls TDialog::SetupWindow to set up the window, then limits the number of characters the user can enter to bufferSize - 1.


TInStream Class

OWL Hierarchy

Header File

docview.h

Description

Derived from TStream and istream, TInStream is a base class used to define input streams for documents.

Public Constructor

TInStream(TDocument& doc, const char far* name, int mode);


TInStream Public Constructor

See Also	TInStream

Syntax

TInStream(TDocument& doc, const char far* name, int mode);

Description

Constructs a TInStream object. doc refers to the document object, name is the user-defined name of the stream, and mode is the mode of opening the stream.


See Also

TOutStream

ofXXXX document open enum

shdocument sharing enum


TLangId typedef

See Also

Header File

locale.h

Syntax

typedef unsigned short TLangId;

Description

Holds a language ID, a predefined number that represents a base language and dialect. For example, the number 409 represents American English. TLocaleString uses the language ID to find the correct translation for strings.


See Also

TLocaleString


TLayoutConstraint struct

OWL Hierarchy

Header File

layoutco.h

Description

TLayoutConstraint is a structure that defines a relationship (a layout constraint) between an edge or size of one window and an edge or size of one of the window's siblings or its parent. If a parent-child relationship is established between windows, the dimensions of the child windows are dependent on the parent window. A window can have one of its sizes depend on the size of the opposite dimension. For example, the width can be twice the height. TLayoutMetrics lists the relationships you can have among size and edge constraints

The following window is displayed by the sample program LAYOUT.CPP, which demonstrates layout constraints:

Setting Up Layout Constraints

Public Data Members

uint MyEdge;

uint OtherEdge;

TRelationship Relationship;

TWindow *RelWin;

TMeasurementUnits Units;

union {

int  Margin;

int  Value;

int  Percent;

};


Setting Up Layout Constraints


TLayoutConstraint MyEdge
TLayoutConstraint::MyEdge

See Also	TLayoutConstraint struct

Syntax

uint MyEdge;

Description

MyEdge contains the name of the edge or size constraint (lmTop, lmBottom, lmLeft, lmRight, lmCenter, lmWidth, or lmHeight) for your window.


See Also

TWidthHeight enum


TLayoutConstraint::OtherEdge

See Also	TLayoutConstraint struct

Syntax

uint OtherEdge;

Description

OtherEdge contains the name of the edge or size constraint (lmTop, lmBottom, lmLeft, lmRight, lmCenter, lmWidth, or lmHeight) for the other window.


See Also

TWidthHeight enum


TLayoutConstraint::Relationship

See Also	TLayoutConstraint struct

Syntax

TRelationship Relationship;

Description

Relationship specifies the type of relationship that exists between the two windows (that is, lmRightOf, lmLeftOf, lmAbove, lmBelow, lmSameAs, or lmPercentOf). A value of lmAbsolute actually indicates that no relationship exists.


See Also

TRelationship enum


TLayoutConstraint::RelWin

See Also	TLayoutConstraint struct

Syntax

TWindow *RelWin;

Description

RelWin is a pointer to the sibling windows or lmParent if the child is a proportion of the parent's dimensions. RelWin points to the window itself (this) if a child window's dimension is a proportion of one of its other dimensions (for example, its height is a proportion of its width).


See Also

TRelationship enum


TLayoutConstraint::Units

See Also	TLayoutConstraint struct

Syntax

TMeasurementUnits Units;

Description

Units enumerates the units of measurement (either pixels or layout units) used to measure the height and width of the windows. Unlike pixels, layout units are based on system font size and will be consistent in their perceived size even if the screen resolution changes.


See Also

TMeasurementUnits enum


TLayoutConstraint::union TLayoutConstraint

See Also	TLayoutConstraint struct

Syntax

union {

int  Margin;

int  Value;

int  Percent;

};

Description

This union is included for the convenience of naming the layout constraints. Margin is used for the ImAbove, ImLeftOf, ImLeftOf, or ImRightOf enumerated values in TRelationship. Value is used for the ImSameAs or ImAbsolute enumerated values in TRelationship. Percent is used for the ImPercentOf enumerated value in TRelationship.


See Also

TMeasurementUnits enum


TLayoutMetrics Class

OWL Hierarchy

Header File

layoutwi.h

Description

Contains the four layout constraints used to define the layout metrics for a window. The following table lists the constraints you can use for the X, Y, Height, and Width fields.

Field	Constraints

X	lmLeft, lmCenter, lmRight

Y	lmTop, lmCenter, lmBottom

Height	lmCenter, lmRight, lmWidth

Width	lmCenter, lmBottom, lmHeight

If the metrics for the child window are relative to the parent window, the relation window pointer needs to be lmParent (not the actual parent window pointer). For example,

TWindow* child = new TWindow(this, "");

TLayoutMetrics metrics;

metrics.X.Set(lmCenter, lmSameAs, lm()t, lmCenter);

metrics.Y.Set(lmCenter, lmSameAs, lm()t, lmCenter);

SetChildLayoutMetrics(*child, metrics);

The parent window pointer (this) should not be used as the relation window pointer of the child window.

Public Data Members

TEdgeOrWidthConstraint Height;

TEdgeOrWidthConstraint Width;

TEdgeConstraint X, Y;

Public Constructor

TLayoutMetrics();


TLayoutMetrics::
TLayoutMetrics::Height

TLayoutMetrics

Syntax

TEdgeOrWidthConstraint Height;

Description

Contains the height size constraint, center edge constraint, or bottom edge constraint of the window.


TLayoutMetrics::Width

TLayoutMetrics

Syntax

TEdgeOrWidthConstraint Width;

Description

Contains the width size constraint, center edge constraint, or right edge (lmRight) constraint of the window.


TLayoutMetrics::X, Y

TLayoutMetrics

Syntax

TEdgeConstraint X, Y;

Description

X contains the X (left, center, right) edge constraint of the window. Y contains the Y (top, center, bottom) edge constraint of the window.


TLayoutMetrics Public Constructor

TLayoutMetrics

Syntax

TLayoutMetrics();

Description

Creates a TLayoutMetrics object and initializes the object. It sets the units for the child and parent window to the specified layout units, and the relationship between the two windows to what is defined in ImAsIs (of TRelationship). TLayoutMetrics sets the following default values:

X.RelWin = 0;

X.MyEdge = lmLeft;

X.Relationship = lmAsIs;

X.Units = lmLayoutUnits;

X.Value = 0;

Y.RelWin = 0;

Y.MyEdge = lmTop;

Y.Relationship = lmAsIs;

Y.Units = lmLayoutUnits;

Y.Value = 0;

Width.RelWin = 0;

Width.MyEdge = lmWidth;

Width.Relationship = lmAsIs;

Width.Units = lmLayoutUnits;

Width.Value = 0;

Height.RelWin = 0;

Height.MyEdge = lmHeight;

Height.Relationship = lmAsIs;

Height.Units = lmLayoutUnits;

Height.Value = 0;

The following program creates two child windows and a frame into which you can add layout constraints.

#include <owl\owl.h>

#include <owl\framewin.h>

#include <owl\applicat.h>

#include <owl\layoutwi.h>

#include <owl\decorate.h>

#include <owl\decmdifr.h>

#include <owl\layoutco.h>

#pragma hdrstop

// Create a derived class. //

class TMyDecoratedFrame : public TDecoratedFrame {

public:

  TMyDecoratedFrame(TWindow* parent, const char far* title,
                    TWindow& clientWnd, TWindow* MyChildWindow);

  void SetupWindow();

  {

    TDecoratedFrame::SetupWindow();

    MyChildWindow->ShowWindow(SW_NORMAL);

    MyChildWindow->BringWindowToTop();

  }

};

// Setup a frame window. //

TMyDecoratedFrame::TMyDecoratedFrame(TWindow * parent,

                                     const char far * title,

                                     TWindow& clientWnd)

  : TDecoratedFrame(parent, title, clientWnd),

    TFrameWindow(parent, title, &clientWnd),

    TWindow(parent, title)

{

// Create a new TMyChildWindow. //

  MyChildWindow = new TWindow(this, "");

  MyChildWindow->Attr.Style |=  WS_BORDER |WS_VISIBLE |WS_CHILD;

  MyChildwindow->SetBkgndColor(RGB(0,100,0));

// Establish metrics for the child window. //

  TLayoutMetrics  layoutMetrics;

  layoutMetrics.X.Absolute(lmLeft, 10);

  layoutMetrics.Y.Absolute(lmTop, 10);

  layoutMetrics.Width.Absolute( 80 );

  layoutMetrics.Height.Absolute( 80 );

}

  SetChildLayoutMetrics(*MyChildWindow, layoutMetrics);

class TMyApp : public TApplication {

public:

  virtual void InitMainWindow()

  {

    TWindow* client = new TWindow(0, "title");

    MainWindow = new TMyDecoratedFrame(0,

                                       "Layout Window Ex",

                                       *client);

  }

};

int OwlMain(int, char**) {

  return TMyApp.Run();

}


TLayoutWindow Class

See Also	OWL Hierarchy	Examples	Inheritance

Header File

layoutwi.h

Description

Derived from TWindow, TLayoutWindow provides functionality for defining the layout metrics for a window. By using layout constraints, you can create windows whose position and size are proportional to another window's dimensions, so that one window constrains the size of the other window. Toolbars and status bars are examples of constrained windows.

Public Constructor and destructor

TLayoutWindow(TWindow* parent, const char far *title = 0, TModule* module = 0);

~TLayoutWindow();

Public Member Functions

bool GetChildLayoutMetrics(TWindow &child, TLayoutMetrics &metrics);

void Layout();

bool RemoveChildLayoutMetrics(TWindow &child);

void SetChildLayoutMetrics(TWindow &child, TLayoutMetrics &metrics);

Protected Data Member

TSize ClientSize;

Protected Member Functions

void EvSize(uint sizeType, TSize& size);

Response Table Entries

EV_ macros and member functions


See Also

TLayoutConstraint defines layout constraints.

TLayoutMetrics describes the metrics you can use to set up layout constraints.


TLayoutWindow Examples

TLayoutWindow

The following examples show how to set up various metrics using edge constraints. For purposes of illustration, these examples use a parent-child relationship, but you can also use a child-to-child (sibling) relationship. Keep in mind that moving the parent's origin (the left and top edges) also moves the child window.

Example 1

To create windows that can grow, set the top and left edges of the child window's boundaries in a fixed relationship to the top and left edges of the parent's window. In this example, if you expand the bottom and right edges of the parent, the child's bottom and right edges grow the same amount. Both the X and Y constraints are 10 units from the parent window's edges. Both the Width and Height constraints are 40 layout units from the parent window's edges. Specifically, Width (lmWidth) is 40 units to the left of the parent's right edge (lmLeftOf = lmSameAs + offset or sameas - 40).

Use the following layout constraints:

layoutmetrics.X.Set(lmLeft, lmRightOf, lmParent, lmLeft, 10);

layoutmetrics.Y.Set(lmTop, lmBelow, lmParent, lmTop, 10);

layoutmetrics.Width.Set(lmRight, lmLeftOf, lmParent, lmRight, 40);

layoutmetrics.Height.Set(lmBottom, lmAbove, lmParent, lmBottom, 40);

SetChildLayoutMetrics(*MyChildWindow, layoutMetrics);

Example 2

To create fixed-size and fixed-position windows, set the child's right edge a fixed distance from the parent's left edge, and the child's bottom edge a fixed distance from the parent's top edge. In this example, both the X and Y edge constraints are set to 10 and both the Width and Height edge constraints are set to 100.

Use the following layout constraints:

layoutmetrics.X.Set(lmLeft, lmRightOf, lmParent, lmLeft, 10);

layoutmetrics.Y.Set(lmTop, lmBelow, lmParent, lmTop, 10);

layoutmetrics.Width.Absolute(100);

layoutmetrics.Height.Absolute(100);

SetChildLayoutMetrics(*MyChildWindow, layoutMetrics);

Example 3

To create a fixed-size window that remains a constant distance from the parent's right corner, set the child's top and bottom edges a fixed distance (lmLayout unit or pixels) from the parent window's bottom. Also, set the child's left and right edges a fixed distance from the parent's right edge. In this example, both the Width and the Height edge constraints are set to 100 and the X and Y edge constraints are set to 10. In this case, the child window, which stays the same size, moves with the lower right corner of the parent.

Use the following layout constraints:

layoutmetrics.X.Set(lmRight, lmLeftOf, lmParent, lmRight, 10);

layoutmetrics.Y.Set(lmBottom, lmAbove, lmParent, lmBottom, 10);

layoutmetrics.Width.Absolute(100);

layoutmetrics.Height.Absolute(100);

SetChildLayoutMetrics(*MyChildWindow, layoutMetrics);

Example 4

To create a window in which the child's edges are a percentage of the parent's window, set the child's edges a percentage of the distance from the parent's edges. Specifically, the child's top and bottom edges are a percentage of the parent's bottom edge. The child's left and right edges are a percentage of the parent's right edge.

If you resize the parent window, the child window will change size and origin (that is, the top and left edges will also change).

Use the following layout constraints:

layoutmetrics.X.Set(lmLeft, lmPercentOf, lmParent, lmRight, 33);

layoutmetrics.Y.Set(lmTop, lmPercentOf, lmParent, lmBottom, 33);

layoutmetrics.Width.Set(lmRight, lmPercentOf, lmParent, lmRight, 66);

layoutmetrics.Height.Set(lmBottom, lmPercentOf, lmParent, lmBottom, 66);

SetChildLayoutMetrics(*MyChildWindow, layoutMetrics);


TLayoutWindow Public Constructor and Destructor

TLayoutWindow

Constructor

TLayoutWindow(TWindow* parent, const char far *title = 0, TModule* module = 0);

Destructor

~TLayoutWindow();

Description

Creates a TLayoutWindow object with specified parent, window caption, and library ID.

Destructor

Deletes variables and frees the child metrics and constraints.


TLayoutWindow::GetChildLayoutMetrics

TLayoutWindow

Syntax

bool GetChildLayoutMetrics(TWindow &child, TLayoutMetrics &metrics);

Description

Gets the layout metrics of the child window.


TLayoutWindow::Layout

TLayoutWindow

Syntax

void Layout();

Description

Causes the window to resize and position its children according to the specified metrics. You can call Layout to implement changes that occur in the layout metrics.


TLayoutWindow::RemoveChildLayoutMetrics

TLayoutWindow

Syntax

bool RemoveChildLayoutMetrics(TWindow &child);

Description

Removes the layout metrics for a child window.


TLayoutWindow::SetChildLayoutMetrics

TLayoutWindow

Syntax

void SetChildLayoutMetrics(TWindow &child, TLayoutMetrics &metrics);

Description

Sets the metrics for the window and removes any existing ones. Set the metrics as shown:

layoutMetrics->X.Absolute(lmLeft, 10);

layoutMetrics->Y.Absolute(lmTop, 10);

layoutMetrics->Width.Set(lmWidth, lmRightOf, GetClientWindow(), lmWidth, -40);

layoutMetrics->Height.Set(lmHeight, lmRightOf, GetClientWindow(), lmHeight, -40);

Then call SetChildLayoutMetrics to associate them with the position of the child window:

SetChildLayoutMetrics(* MyChildWindow, * layoutMetrics);


TLayoutWindow::ClientSize

TLayoutWindow

Syntax

TSize ClientSize;

Description

Contains the size of the client area.


TLayoutWindow::EvSize

TLayoutWindow

Syntax

void EvSize(uint sizeType, TSize& size);

Description

Responds to a change in window size by calling Layout to resize the window.


TLayoutWindow Response Table Entries

TLayoutWindow

Response table entry	Member function

EV_WM_SIZE	EvSize


TListBox Class

OWL Hierarchy	Inheritance

Header File

listbox.h

Description

An interface object that represents a corresponding list box element. A TListBox must be used to create a list box control in a parent TWindow. A TListBox can be used to facilitate communication between your application and the list box controls of a TDialog object. TListBox's member functions also serve instances of its derived class TComboBox. From within MDI child windows, you can access a TListBox object by using TFrameWindow::GetClientWindow. TListBox is a streamable class.

Public Constructors

TListBox(TWindow* Parent, int Id, int x, int y, int w, int h, TModule* module = 0);

TListBox(TWindow* Parent, int resourceId, TModule* module = 0)

Public Member Functions

virtual int AddString(const char far* str);

virtual void ClearList();

virtual int DeleteString(int index);

virtual int DirectoryList(uint attrs, const char far* fileSpec)

int FindExactString(const char far* str, int searchIndex) const;

virtual int FindString(const char far* str, int Index) const;

int GetCaretIndex() const;

virtual int GetCount() const;

int GetHorizontalExtent() const;

virtual uint32 GetItemData(int index) const;

virtual int GetItemHeight(int index) const;

int GetItemRect(int index, TRect& rect) const;

bool GetSel(int index) const;

int GetSelCount() const;

virtual int GetSelIndex() const;

int GetSelIndexes(int* indexes, int maxCount) const;

int GetSelString(char far* str, int maxChars) const;

int GetSelStrings(char far** strs, int maxCount, int maxChars) const;

virtual int GetString(char far* str, int index) const;

virtual int GetStringLen(int Index) const;

int GetTopIndex() const;

virtual int InsertString(const char far* str, int index);

int SetCaretIndex(int index, bool partScrollOk);

void SetColumnWidth(int width);

void SetHorizontalExtent(int horzExtent);

virtual int SetItemData(int index, uint32 itemData);

virtual int SetItemHeight(int index, int height);

int SetItemRect(int index, TRect& rect) const;

int SetSel(int index, bool select);

virtual int SetSelIndex(int index);

int SetSelIndexes(int* indexes, int numSelections, bool shouldSet);

int SetSelItemRange(bool select, int first, int last);

int SetSelString(const char far* str, int searchIndex);

int SetSelStrings(const char far** prefixes, int numSelections, bool shouldSet);

bool SetTabStops(int numTabs, int far* tabs);

int SetTopIndex(int index);

uint Transfer(void *buffer, TTransferDirection direction);

Protected Member Function

char far* GetClassName();


TListBox Public Constructors

See Also	TListBox

Syntax 1

TListBox(TWindow* parent, int Id, int x, int y, int w, int h, TModule* module = 0);

Description

Constructs a list box object with the supplied parent window (parent) library ID (module), position (x, y) relative to the origin of the parent window's client area, width (w), and height (h). Invokes a TControl constructor. Adds LBS_STANDARD to the default styles for the list box to provide it with

A border (WS_BORDER)

A vertical scroll bar (WS_VSCROLL)

Automatic alphabetic sorting of list items (LBS_SORT)

Parent window notification upon selection (LBS_NOTIFY)

The TListBox member functions that are described as being for single-selection list boxes are inherited by TComboBox and can also be used by combo boxes. Also, these member functions return -1 for multiple-selection list boxes.

Syntax 2

TListBox(TWindow* parent, int resourceId, TModule* module = 0)

Description

Constructs a TListBox object to be associated with a list box control of a TDialog object. Invokes the TControl constructor with similar parameters. The module parameter must correspond to a list box resource that you define.


See Also

GetSelIndex

GetSelString


TListBox::AddString

See Also	TListBox

Syntax

virtual int AddString(const char far* str);

Description

Adds string to the list box, returning its position in the list (0 is the first position). Returns a negative value if an error occurs. The list items are automatically sorted unless the style LBS_SORT is not used for list box creation.


See Also

TListBox::DeleteString

TListBox::InsertString


TListBox::ClearList

TListBox

Syntax

virtual void ClearList();

Description

Clears all items in the list.


TListBox::DeleteString

See Also	TListBox

Syntax

virtual int DeleteString(int index);

Description

Deletes the item in the list at the position (starting at 0) supplied in index. DeleteString returns the number of remaining list items, or a negative value if an error occurs.


See Also

TListBox::AddString

TListBox::InsertString


TListBox::DirectoryList

TListBox

Syntax

virtual int DirectoryList(uint attrs, const char far* fileSpec)

Description

Adds a list of file names to a list box.


TListBox::FindExactString

See Also	TListBox

Syntax

int FindExactString(const char far* str, int searchIndex) const;

Description

Starting at the line number passed in searchIndex, searches the list box for an exact match with the string str. If a match is not found after the last string has been compared, the search continues from the beginning of the list until a match has been found or until the list has been completely traversed. Searches from the beginning of the list when -1 is supplied as searchIndex. Returns the index of the first string found if successful, or a negative value if an error occurs.


See Also

TListBox::AddString

TListBox::DeleteString


TListBox::FindString

See Also	TListBox

Syntax

virtual int FindString(const char far* str, int Index) const;

Description

Searches the list box as described under FindExactString, but looks for the first entry that begins with str.


See Also

TListBox::AddString

TListBox::DeleteString

TListBox::InsertString


TListBox::GetCaretIndex

See Also	TListBox

Syntax

int GetCaretIndex() const;

Description

Returns the index of the currently focused list-box item. For single-selection list boxes, the return value is the index of the selected item, if one is selected.


See Also

TListBox::SetCaretIndex


TListBox::GetCount

TListBox

Syntax

virtual int GetCount() const;

Description

Returns the number of items in the list box, or a negative value if an error occurs.


TListBox::GetHorizontalExtent

See Also	TListBox

Syntax

int GetHorizontalExtent() const;

Description

Returns the number of pixels by which the list box can be scrolled horizontally.


See Also

TListBox::SetHorizontalExtent


TListBox::GetItemData

See Also	TListBox

Syntax

virtual uint32 GetItemData(int index) const;

Description

Returns the 32-bit value of the list box item set by SetItemData.


See Also

TListBox::SetItemData


TListBox::GetItemHeight

See Also	TListBox

Syntax

virtual int GetItemHeight(int index) const;

Description

Returns the height in pixels of the specified list box items.


See Also

TListBox::SetItemHeight


TListBox::GetItemRect

TListBox

Syntax

int GetItemRect(int index, TRect& rect) const;

Description

Returns the dimensions of the rectangle that surrounds a list-box item currently displayed in the list-box window.


TListBox::GetSel

See Also	TListBox

Syntax

bool GetSel(int index) const;

Description

Returns the selection state of the list-box item at location index. Returns true if the list-box item is selected, false if not selected.


See Also

TListBox::SetSel


TListBox::GetSelCount

TListBox

Syntax

int GetSelCount() const;

Description

Returns the number of selected items in the single- or multiple-selection list box or combo box.


TListBox::GetSelIndex

See Also	TListBox

Syntax

virtual int GetSelIndex() const;

Description

For single-selection list boxes. Returns the nonnegative index (starting at 0) of the currently selected item, or a negative value if no item is selected.


See Also

TListBox::SetSelIndex


TListBox::GetSelIndexes

See Also	TListBox

Syntax

int GetSelIndexes(int* indexes, int maxCount) const;

Description

For multiple-selection list boxes. Fills the indexes array with the indexes of up to maxCount selected strings. Returns the number of items put in indexes (-1 for single-selection list boxes and combo boxes).


See Also

TListBox::SetSelIndexes


TListBox::GetSelString

See Also	TListBox

Syntax

int GetSelString(char far* str, int maxChars) const;

Description

Retrieves the currently selected items, putting up to maxChars of them in str. Each entry in the str array should have space for maxChars characters and a terminating null. For single-selection list boxes, GetSelString returns one of the following: the string length, a negative value if an error occurs, or 1 if no string is selected. For multiple-selection list boxes, it returns -1.


See Also

TListBox::SetSelString


TListBox::GetSelStrings

See Also	TListBox

Syntax

int GetSelStrings(char far** strs, int maxCount, int maxChars) const;

Description

Retrieves the total number of selected items for a multiselection list and copies them into the buffer. The strs parameter is an array of pointers to chars. Each of the pointers to the buffers is of maxChars. maxCount is the size of the array.


See Also

TListBox::SetSelStrings


TListBox::GetString

TListBox

Syntax

virtual int GetString(char far* str, int index) const;

Description

Retrieves the item at the position (starting at 0) supplied in index and returns it in str. GetString returns the string length, or a negative value if an error occurs.


TListBox::GetStringLen

TListBox

Syntax

virtual int GetStringLen(int Index) const;

Description

Returns the string length (excluding the terminating NULL) of the item at the position index supplied in Index. Returns a negative value in the case of an error.


TListBox::GetTopIndex

See Also	TListBox

Syntax

int GetTopIndex() const;

Description

Returns the index of the first item displayed at the top of the list box.


See Also

TListBox::SetTopIndex


TListBox::InsertString

See Also	TListBox

Syntax

virtual int InsertString(const char far* str, int index);

Description

Inserts str in the list box at the position supplied in index, and returns the item's actual position (starting at 0) in the list. A negative value is returned if an error occurs. The list is not resorted. If index is -1, the string is appended to the end of the list.


See Also

TListBox::AddString

TListBox::DeleteString

TListBox::FindString


TListBox::SetCaretIndex

See Also	TListBox

Syntax

int SetCaretIndex(int index, bool partScrollOk);

Description

Sets the focus to the item specified at index. An item that is not visible is scrolled into view.


See Also

TListBox::GetCaretIndex


TListBox::SetColumnWidth

TListBox

Syntax

void SetColumnWidth(int width);

Description

Sets the width in pixels of the items in the list box.


TListBox::SetHorizontalExtent

See Also	TListBox

Syntax

void SetHorizontalExtent(int horzExtent);

Description

Sets the number of pixels by which the list box can be scrolled horizontally.


See Also

TListBox::GetHorizontalExtent


TListBox::SetItemData

See Also	TListBox

Syntax

virtual int SetItemData(int index, uint32 itemData);

Description

Sets the 32-bit value of the list box item at the specified index position.


See Also

TListBox::GetItemData


TListBox::SetItemHeight

See Also	TListBox

Syntax

virtual int SetItemHeight(int index, int height);

Description

Sets the height in pixels of the items in the list box.


See Also

TListBox::GetItemHeight


TListBox::SetItemRect

TListBox

Syntax

int SetItemRect(int index, TRect& rect) const;

Description

Sets the dimensions of the rectangle that surrounds a list-box item currently displayed in the list-box window.


TListBox::SetSel

See Also	TListBox

Syntax

int SetSel(int index, bool select);

Description

For multiple-selection list boxes. Selects an item at the position specified in index.


See Also

TListBox::GetSel


TListBox::SetSelIndex

TListBox

Syntax

virtual int SetSelIndex(int index);

Description

For single-selection list boxes. Forces the selection of the item at the position (starting at 0) supplied in index. If index is -1, the list box is cleared of any selection. SetSelIndex returns a negative number if an error occurs.


TListBox::SetSelIndexes

TListBox

Syntax

int SetSelIndexes(int* indexes, int numSelections, bool shouldSet);

Description

For multiple-selection list boxes. Selects or deselects the strings in the associated list box at the indexes specified in the Indexes array. If ShouldSet is true, the indexed strings are selected and highlighted; if ShouldSet is false the highlight is removed and they are no longer selected. Returns the number of strings successfully selected or deselected (-1 for single-selection list boxes and combo boxes). If NumSelections is less than 0, all strings are selected or deselected, and a negative value is returned on failure.


TListBox::SetSelItemRange

TListBox

Syntax

int SetSelItemRange(bool select, int first, int last);

Description

Selects the range of items specified from first to last.


TListBox::SetSelString

TListBox

Syntax

int SetSelString(const char far* str, int searchIndex);

Description

For single-selection list boxes. Forces the selection of the first item beginning with the text supplied in str that appears beyond the position (starting at 0) supplied in SearchIndex. If SearchIndex is -1, the entire list is searched, beginning with the first item. SetSelString returns the position of the newly selected item, or a negative value in the case of an error.


TListBox::SetSelStrings

TListBox

Syntax

int SetSelStrings(const char far** prefixes, int numSelections, bool shouldSet);

Description

For multiple-selection list boxes, selects the strings in the associated list box that begin with the prefixes specified in the prefixes array. For each string the search begins at the beginning of the list and continues until a match is found or until the list has been completely traversed. If shouldSet is true, the matched strings are selected and highlighted; if shouldSet is false, the highlight is removed from the matched strings and they are no longer selected. Returns the number of strings successfully selected or deselected (-1 for single-selection list boxes and combo boxes). If numSelections is less than 0, all strings are selected or deselected, and a negative value is returned on failure.


TListBox::SetTabStops

TListBox

Syntax

bool SetTabStops(int numTabs, int far* tabs);

Description

Sets tab stops. numTabs is the number of tab stops. tabs is the array of integers representing the tab positions.


TListBox::SetTopIndex

See Also	TListBox

Syntax

int SetTopIndex(int index);

Description

Sets index to the first item displayed at the top of the list box.


See Also

TListBox::GetTopIndex


TListBox::Transfer

See Also	TListBox

Syntax

uint Transfer(void *buffer, TTransferDirection direction);

Description

Transfers the items and selection(s) of the list box to or from a transfer buffer if tdSetData or tdGetData, respectively, is passed as the direction. buffer is expected to point to a pointer to a TListBoxData structure.

Transfer, which overrides the TWindow virtual member function, returns the size of TListBoxData (the pointer, not the structure). To retrieve the size without transferring data, pass tdSizeData as the direction.

You must use a pointer in your transfer buffer to these structures. You cannot embed copies of the structures in your transfer buffer, and you cannot use these structures as transfer buffers.


See Also

TWindow::Transfer


TListBox::GetClassName

TListBox

Syntax

char far* GetClassName();

Description

Returns the name of TListBox's registration class, "LISTBOX".


TListBoxData struct

OWL Hierarchy	Inheritance

Header File

listbox.h

Description

Used to transfer the contents of a list box.

Public Data Members

TDwordArray* ItemDatas;

int SelCount;

TIntArray* SelIndices

TStringArray* SelStrings;

TStringArray* Strings;

Public Constructor and Destructor

TListBoxData();

~TListBoxData();

Public Member Functions

void AddString(const char *str, bool isSelected = false);

void AddStringItem(const char* str, uint32 itemData, bool isSelected = false));

void Clear();

TDwordArray& GetItemDatas();

TIntArray& GetSelIndices();

void GetSelString(char far* buffer, int bufferSize, int index = 0) const;

int GetSelStringLength(int index = 0) const;

TStringArray& GetStrings();

void ResetSelections();

void Select(int index);

void SelectString(const char far* str);


 TListBoxData::ItemDatas

TListBoxData struct

Syntax

TDwordArray* ItemDatas;

Description

Contains all uint32 item data for each item in the list box.


TListBoxData::SelCount

TListBoxData struct

Syntax

int SelCount;

Description

Holds the number of selected items.


TListBoxData::SelIndices

TListBoxData struct

Syntax

TIntArray* SelIndices;

Description

Contains the indexes of all the selected strings in a multiple-selection list box.


TListBoxData::SelStrings

TLIstBoxData struct

Syntax

TStringArray* SelStrings;

Description

Pointer to an array of the strings to select when data is transferred into the list box. When data is transferred out of the list box, SelStrings returns the current selection(s).


TListBoxData::Strings

TLIstBoxData struct

Syntax

TStringArray* Strings;

Description

Pointer to an array of strings to be transferred into a TListBox.


TListBoxData Public Constructor and Destructor
TListBoxData::Public Constructors and Destructor

TLIstBoxData struct

Constructor

TListBoxData();

Destructor

~TListBoxData();

Description

Constructs Strings and SelStrings. Initializes SelCount to 0.

Destructor

Deletes the space allocated for Strings and SelStrings.


TListBoxData::AddString

TLIstBoxData struct

Syntax

void AddString(const char *str, bool isSelected = false);

Description

Adds the specified string to Strings. If IsSelected is true, adds the string to SelStrings and increments SelCount.


TListBoxData::AddStringItem

TLIstBoxData struct

Syntax

void AddStringItem(const char* str, uint32 itemData, bool isSelected = false));

Description

Adds a string to the Strings array, optionally selects it, and adds item data to the ItemDatas array.


TListBoxData::Clear

See Also	TLIstBoxData struct

Syntax

void Clear();

Description

Resets the list box by flushing the ItemDatas and Strings arrays and calling ResetSelections.


See Also

TListBoxData::Strings

TListBoxData::ItemDatas

TListBoxData::ResetSelections


TListBoxData::GetItemDatas

See Also	TLIstBoxData struct

Syntax

TDwordArray& GetItemDatas();

Description

Returns a pointer to the ItemDatas array.


See Also

TListBoxData::ItemDatas


TListBoxData::GetSelIndices

See Also	TLIstBoxData struct

Syntax

TIntArray& GetSelIndices();

Description

Returns a pointer to the SelIndices array.


See Also

TListBoxData::SelIndices


TListBoxData::GetSelString

TLIstBoxData struct

Syntax

void GetSelString(char far* buffer, int bufferSize, int index = 0) const;

Description

Locates the string at the specified index in SelStrings and copies it into buffer. bufferSize includes the terminating NULL.


TListBoxData::GetSelStringLength

TLIstBoxData struct

Syntax

int GetSelStringLength(int index = 0) const;

Description

Returns the length (excluding the terminating NULL) of the string at the specified index in SelStrings.


TListBoxData::GetString

See Also	TLIstBoxData struct

Syntax

TStringArray& GetStrings();

Description

Returns a pointer to the Strings array.


See Also

TListBoxData::Strings


TListBoxData::ResetSelections

TLIstBoxData struct

Syntax

void ResetSelections();

Description

Removes all strings from SelStrings and sets SelCount to 0.


TListBoxData::Select

TLIstBoxData struct

Syntax

void Select(int index);

Description

Selects the string at the given index.


TListBoxData::SelectString

TLIstBoxData struct

Syntax

void SelectString(const char far* str);

Description

Adds str to SelStrings and increments SelCount.


TListView Class

See Also	OWL Hierarchy	Inheritance

Header File

listview.h

Description

Provides views for list boxes.

Public Constructor and Destructor

TListView(TDocument& doc, TWindow* ()t = 0);

~TListView();

Public Data Member

bool DirtyFlag;

Public Member Functions

bool CanClose();

virtual bool Create();

const char far* GetViewName();

TWindow* GetWindow();

bool SetDocTitle(const char far* docname, int index);

static const char far* StaticName();

Protected Data Members

int MaxWidth;

long Origin;

Protected Member Functions

void CmEditAdd();

void CmEditClear();

void CmEditCopy();

void CmEditCut();

void CmEditDelete();

void CmEditItem();

void CmEditPaste();

void CmSelChange();

uint EvGetDlgCode(MSG far* msg);

bool LoadData(int top, int sel);

void SetExtent(LPSTR str);

bool VnCommit(bool force);

bool VnDocClosed(int omode);

bool VnIsDirty();

bool VnIsWindow(HWND hWnd);

bool VnRevert(bool clear);

Response Table Entries

EV_ macros and member functions


See Also

TView describes the view functions.

TListBox describes the list box functions.


TListView Public Constructor and Destructor
TListView Public Constructors and Destructor

TListView

Constructor

TListView(TDocument& doc, TWindow* parent = 0);

Destructor

~TListView();

Description

Creates a TListView object associated with the specified document and parent window. Sets Attr.AccelTable to IDA_LISTVIEW to identify the edit view. Sets the view style to WS_HSCROLL | LBS_NOINTEGRALHEIGHT.

Sets TView::ViewMenu to the new TMenuDescr for this view.

Destructor

After checking to see if there is an open view, this destructor destroys the TListView object.


TListView::DirtyFlag

TListView

Syntax

bool DirtyFlag;

Description

Has a nonzero value if the data in the list view has been changed; otherwise, is 0.


TListView::CanClose

TListView

Syntax

bool CanClose();

Description

Checks to see if all child views can be closed before closing the current view. If any child returns 0, CanClose returns 0 and aborts the process. If all children return nonzero, it calls TDocManager::FlushDoc.


TListView::Create

TListView

Syntax

virtual bool Create();

Description

Overrides TWindow::Create and creates the view's window. Determines if the file is new or already has data. If there is data, calls LoadData to add the data to the view. If the view's window can't be created, Create throws a TXWindow exception.


TListView::GetViewName

TListView

Syntax

const char far* GetViewName();

Description

Overrides TView's virtual GetViewNamefunction and returns the descriptive name of the class (StaticName).


TListView::GetWindow

TListView

Syntax

TWindow* GetWindow();

Description

Overrides TView's virtual GetWindowfunction and returns the list view object as a TWindow.


TListView::SetDocTitle

TListView

Syntax

bool SetDocTitle(const char far* docname, int index);

Description

Overrides TView's virtual SetDocTitlefunction and stores the document title. This name is forwarded up the parent chain until a TFrameWindow object accepts the data and displays it in its caption.


TListView::StaticName

See Also	TListView

Syntax

static const char far* StaticName();

Description

Returns a constant string for the view name, ListView. This information is displayed in the user interface selection box.


See Also

TView::GetViewName


TListView::MaxWidth

TListView

Syntax

int MaxWidth;

Description

Holds the maximum horizontal extent (the number of pixels by which the view can be scrolled horizontally).


TListView::Origin

TListView

Syntax

long Origin;

Description

Holds the file position at the beginning of the display.


TListView::CmEditAdd

TListView

Syntax

void CmEditAdd();

Description

Automatically responds to CM_LISTADD message by getting the length of the input string and inserting the text string into the list view. Sets the data member DirtyFlag to true.


TListView::CmEditCopy

TListView

Syntax

void CmEditCopy();

Description

Automatically responds to a menu selection with a menu ID of CM_EDITCOPY and copies the selected text to the Clipboard.


TListView::CmEditClear

TListView

Syntax

void CmEditClear();

Description

Automatically responds to a menu selection with a menu ID of CM_EDITCLEAR by clearing the items in the list box using functions in TListBox.


TListView::CmEditCut

TListView

Syntax

void CmEditCut();

Description

Automatically responds to a menu selection with a menu ID of CM_EDITCUT by calling CmEditCopy and CmEditDelete to delete a text string from the list view. Sets the data member DirtyFlag to true.


TListView::CmEditDelete

TListView

Syntax

void CmEditDelete();

Description

Automatically responds to a menu selection with a menu ID of CM_EDITDELETE by deleting the currently selected text.


TListView::CmEditItem

TListView

Syntax

void CmEditItem();

Description

Automatically responds to a CM_LISTEDIT message by getting the input text and inserting into the list view. Sets DirtyFlag to a nonzero value to indicate that the view has been changed and not saved.


TListView::CmEditPaste

TListView

Syntax

void CmEditPaste();

Description

Automatically responds to a menu selection with a menu ID of CM_EDITPASTE by inserting text into the list box using functions in TListBox.


TListView::CmSelChange

TListView

Syntax

void CmSelChange();

Description

Automatically responds to a LBN_SELCHANGE message (which indicates that the contents of the list view have changed) by calling TWindow::DefaultProcessing.


TListView::EvGetDlgCode

See Also	TListView

Syntax

uint EvGetDlgCode(MSG far* msg);

Description

Overrides TWindow's response to a WM_GETDLGCODE message (an input procedure associated with a control that isn't a check box) by calling TWindow::DefaultProcessing. The msg parameter indicates the kind of message, for example a control or a command message, sent to the dialog box manager.

EvGetDlgCode returns a code that indicates how the list box control message is to be treated.


See Also

TButton::EvGetDlgCode

DLGC_xxxxdialogcontrolmessageconstants


TListView::LoadData

TListView

Syntax

bool LoadData(int top, int sel);

Description

Reads the view from the stream and closes the file. Returns true if the view was successfully loaded.

Throws an xmsg exception and displays the error message TListView initial read error if the file can't be read. Returns false if the view can't be loaded.


TListView::SetExtent

TListView

Syntax

void SetExtent(LPSTR str);

Description

Sets the maximum horizontal extent for the list view window.


TListView::VnCommit

See Also	TListView

Syntax

bool VnCommit(bool force);

Description

Commits changes made in the view to the document. If force is nonzero, all data, even if it's unchanged, is saved to the document.


See Also

TListView::vnRevert

vnxxxx view notification constants


TListView::VnDocClosed

See Also	TListView

Syntax

bool VnDocClosed(int omode);

Description

Indicates that the document has been closed.


See Also

vnxxxx view notification constants


TListView::VnIsDirty

See Also	TListView

Syntax

bool VnIsDirty();

Description

Returns a nonzero value if changes made to the data in the view have not been saved to the document; otherwise, returns 0.


See Also

vnxxxx view notification constants


TListView::VnIsWindow

See Also	TListView

Syntax

bool VnIsWindow(HWND hWnd);

Description

Returns a nonzero value if the window's handle passed in hWnd is the same as that of the view's display window.


See Also

vnxxxx view notification constants


TListView::VnRevert

See Also	TListView

Syntax

bool VnRevert(bool clear);

Description

Indicates if changes made to the view should be erased, and if the data from the document should be restored to the view. If clear is a nonzero value, the data is cleared instead of restored to the view.


See Also

TListView::vnCommit


TListView Response Table Entries

TListView

Entry	Member function

EV_COMMAND(CM_LISTUNDO, CmEditUndo)	CmEditUndo

EV_COMMAND(CM_LISTCUT, CmEditCut)	CmEditcut

EV_COMMAND(CM_LISTCOPY, CmEditCopy)	CmEditCopy

EV_COMMAND(CM_LISTPASTE, CmEditPaste)	CmEditPaste

EV_COMMAND(CM_LISTCLEAR, CmEditClear)	CmEditClear

EV_COMMAND(CM_LISTDELETE, CmEditDelete)	CmEditDelete

EV_COMMAND(CM_LISTADD, CmEditAdd)	CmEditAdd

EV_COMMAND(CM_LISTEDIT, CmEditItem)	CmEditItem

EV_WM_GETDLGCODE 	EvGetDlgCode

EV_NOTIFY_AT_CHILD(LBN_DBLCLK, CmEditItem)	CmEditItem

EV_NOTIFY_AT_CHILD(LBN_SELCHANGE, CmSelChange)	CmSelchange

EV_VN_DOCCLOSED 	VnDocClosed

EV_VN_ISWINDOW 	VnIsWindow

EV_VN_ISDIRTY 	VnIsDirty

EV_VN_COMMIT 	VnCommit

EV_VN_REVERT 	VnRevert


TLocaleString Struct

See Also	OWL Hierarchy

Header File

locale.h

Description

Designed to provide support for localized registration parameters, the TLocaleString struct defines a localizable substitute for char* strings. These strings, which describe both OLE and non-OLE enabled objects to the user, are available in whatever language the user needs. This struct supports ObjectWindows' Doc/View as well as ObjectComponents' OLE-enabled applications. The public member functions, which supply information about the user's language, the native language, and a description of the string marked for localization, simplify the process of translating and comparing strings in a given language.

To localize the string resource, TLocaleString uses several user-entered prefixes to determine what kind of string to translate. Each prefix must be followed by a valid resource identifier (a standard C identifier).The following table lists the prefixes TLocaleString  uses to localize strings. Each prefix is followed by a sample entry.

Prefix 	Description

@ TXY	The string is a series of characters interpreted as a resource ID and is accessed only from a resource file. It is never used directly.

# 1045	The string is a series of digits interpreted as a resource ID and is accessed from a resource file. It is never used directly.

! MyWindow	The string is translated if it is not in the native language; otherwise, this string is used directly.

See the section on localizing symbol names in the ObjectWindows Programmer's Guide for more information about localizing strings.

Public Member Functions

int Compare(const char far* str, TLangId lang);

static TLangId GetSystemLangId();

static TLangId GetUserLangId();

static int IsNativeLangId(TLangId lang);

operator const char*();

void operator =(const char* str);

const char* Translate(TLangId lang);


See Also

TLangId typedef

LangXxxx_ID constants


TLocaleString::Compare

TLocaleString

Syntax

int Compare(const char far* str, TLangId lang);

Description

Using the specified language (lang), Compare compares TLocaleString with another string. It uses the standard string compare and the language-specific collation scheme. It returns one of the following values.

Return value	Meaning

0	There is no match between the two strings.

1	This string is greater than the other string.

-1	This string is less than the other string.


TLocaleString::GetSystemLangId

See Also	TLocaleString

Syntax

static TLangId GetSystemLangId();

Description

Returns the system language ID, which can be the same as the UserLangId.


See Also

TLocaleString::GetUserLangId


TLocaleString::GetUserLangId

See Also	TLocaleString

Syntax

static TLangId GetUserLangId();

Description

Returns the user language ID. For single user systems, this is the same as LangSysDefault. The language ID is a predefined number that represents a base language and dialect.


See Also

TLocaleString::GetSystemLangId


TLocaleString::IsNativeLangId

TLocaleString

Syntax

static int IsNativelangId(TLangId lang);

Description

Returns true if lang equals the native system language.


TLocaleString::operator const char*

TLocaleString

Syntax

operator const char* ();

Description

Returns the current character string in the translation.


TLocaleString::operator =

TLocaleString

Syntax

void operator = (const char* str);

Description

Assigns the string (str) to this locale string.


TLocaleString::Translate

TLocaleString

Syntax

const char* Translate(TLangId lang);

Description

Translates the string to the given language. Translate follows this order of preference in order to choose a language for translation:

1.	Base language and dialect.

2.	Base language and no dialect.

3.	Base language and another dialect.

4.	The native language of the resource itself.

5.	Returns 0 if unable to translate the string. (This can happen only if an @ or # prefix is used; otherwise, the ! prefix indicates that the string following is the native language itself.)


TLookupValidator Class

OWL Hierarchy	Inheritance

Header File

validate.h

Description

A streamable class, TLookupValidator compares the string typed by a user with a list of acceptable values. TLookupValidator is an abstract validator type from which you can derive useful lookup validators. You will never create an instance of TLookupValidator. When you create a lookup validator type, you need to specify a list of valid items and override the Lookup method to return true only if the user input matches an item in that list. One example of a working descendant of TLookupValidator is TStringLookupValidator.

Public Constructor

TLookupValidator();

Public Member Functions

bool IsValid(const char far* str);

virtual bool Lookup(const char far* str);


TLookupValidator Public Constructor

TLookupValidator

Syntax

TLookupValidator();

Description

Constructs a TLookupValidator object.


TLookupValidator::IsValid

TLookupValidator

Syntax

bool IsValid(const char far* str);

Description

IsValid overrides TValidator's virtual function and calls Lookup to find the string str in the list of valid input items. IsValid returns true if Lookup returns true, meaning Lookup found str in its list; otherwise, it returns false.


TLookupValidator::Lookup

TLookupValidator

Syntax

virtual bool Lookup(const char far* str);

Description

Searches for the string str in the list of valid entries and returns true if it finds str; otherwise, returns false. TLookupValidator's Lookup is an abstract method that always returns false. Descendant lookup validator types must override Lookup to perform a search based on the actual list of acceptable items.


TMDIChild Class

OWL Hierarchy	Inheritance

Header File

mdichild.h

Description

TMDIChild defines the basic behavior of all MDI child windows. Child windows can be created inside the client area of a parent window. Because child windows exist within, and are restricted to the parent window's borders,  the parent window defined before the child is defined. For example, a dialog box is a window that contains child windows, often referred to as dialog box controls.

To be used as MDI children, classes must be derived from TMDIChild. MDI children can inherit keyboard navigation, focus handling, and icon support from TFrameWindow. TMDIChild is a streamable class.

Public Constructors and destructor

TMDIChild(TMDIClient& parent, const char far* title = 0, TWindow* clientWnd = 0, bool shrinkToClient = false, TModule* module = 0);

TMDIChild(HWND hWnd, TModule* module = 0);

~TMDIChild();

Public Member Functions

void Destroy(retVal = 0);

bool EnableWindow(bool enable);

bool PreProcessMsg (MSG& msg);

void ShowWindow(int cmdShow);

Protected Member Functions

LRESULT DefWindowProc (uint msg, WPARAM wParam, LPARAM lParam);

void EvMDIActivate(HWND hWndActivated, HWND hWndDeactivated);

bool EvNCActivate(bool active);

void PerformCreate(int menuOrId);

Response Table Entries

EV_ macros and member functions


TMDIChild Public Constructors and Destructor

TMDIChild

Form 1

TMDIChild(TMDIClient& parent, const char far* title = 0, TWindow* clientWnd = 0, bool shrinkToClient = false, TModule* module = 0);

Form 2

TMDIChild(HWND hWnd, TModule* module = 0);

Description

Form 1: Creates an MDI child window of the MDI client window specified by parent, using the specified title, client window (clientWnd) and instance (inst). Invokes the TFrameWindow base class constructor, supplying parent, title, clientWnd, inst, and indicating that the child window is not to be resized to fit. Invokes the TWindow base class constructor, specifying parent, title, and inst. The window attributes are then adjusted to include WS_VISIBLE, WS_CHILD, WS_CLIPSIBLINGS, WS_CLIPCHILDREN, WS_SYSMENU, WS_CAPTION, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX. The dimensions of the window are set to the system default values.

Form 2: Creates an MDI child window object from a preexisting window, specified by hWnd. The base class TFrameWindow constructor is invoked, specifying this hWnd, as well as the specified inst. The base class TWindow constructor is invoked, supplying the hWnd and inst parameters.

Destructor

~TMDIChild();

Destructs the MDI child window object.


TMDIChild::Destroy

See Also	TMDIChild

Syntax

void Destroy(retVal = 0);

Description

Destroys the interface element associated with the TMDIChild. Calls EnableAutoCreate for each window in the child list so that the children are also re-created when the parent window is re-created.


See Also

TWindow::EnableAutoCreate


TMDIChild::EnableWindow

TMDIChild

Syntax

bool EnableWindow(bool enable);

Description

Overrides TWindow's virtual function. Enables a child window.


TMDIChild::PreProcessMsg

See Also	TMDIChild

Syntax

bool PreProcessMsg (MSG& msg);

Description

Performs preprocessing of window messages for the MDI child window. If keyboard handling is enabled the parent client window's TMDIClient_PreProcessMsg member function is called to preprocess messages. In this case, the return value is true. Otherwise, TFrameWindow::PreProcessMsg is called and its return value becomes the return value of this member function.


See Also

TMDIClient::PreProcessMsg

TFrameWindow::PreprocessMsg


TMDIChild::ShowWindow

TMDIChild

Syntax

bool ShowWindow(int cmdShow);

Description

Overrides TWindow's virtual function. Displays a child window according to the value of cmdShow.


TMDIChild::DefWindowProc

See Also	TMDIChild

Syntax

LRESULT DefWindowProc (uint msg, WPARAM wParam, LPARAM lParam);

Description

Overrides TWindow::DefWindowProc to provide default processing for any incoming message the MDI child window does not process. In addition, DefWindowProc handles the following messages: WM_CHILDACTIVATE, WM_GETMINMAXINFO, WM_MENUCHAR, WM_MOVE, WM_SETFOCUS, WM_SIZE, and WM_SYSCOMMAND.


See Also

TWindow::DefWindowProc


TMDIChild::EvMDIActivate

TMDIChild

Syntax

void EvMDIActivate(HWND hWndActivated, HWND hWndDeactivated);

Description

Instructs a client window to activate or deactivate an MDI child window and then sends a message to the child window being activated and the child window being deactivated.


TMDIChild::EvNCActivate

TMDIChild

Syntax

void EvNCActivate(bool activate);

Description

Responds to a request to change a title bar or icon.


TMDIChild::PerformCreate

TMDIChild

Syntax

void PerformCreate(int menuOrId);

Description

Creates the interface element associated with the MDI child window. Otherwise, it notifies the parent MDI client window to create the child window's interface element. The supplied menuOrId parameter is ignored because MDI child windows cannot have menus.


TMDIChild::Response Table Entries

TMDIChild

Response table entry	Member function

EV_WM_MDIACTIVATE	EvMDIActivate

EV_WM_NCACTIVATE	EvNCActivate


TMDIClient Class

OWL Hierarchy	Inheritance

Header File

mdi.h

Description

Multiple Document Interface (MDI) client windows (represented by a TMDIClient object) manage the MDI child windows of a TMDIFrame parent. TMDIClient is a streamable class.

Public Data Member

LPCLIENTCREATESTRUCT ClientAttr;

Public Constructor and destructor

TMDIClient(TModule* module = 0);

~TMDIClient();

Public Member Functions

virtual void ArrangeIcons();

virtual void CascadeChildren();

virtual bool CloseChildren();

bool Create();

virtual TWindow* CreateChild();

TMDIChild *GetActiveMDIChild();

virtual TMDIChild *InitChild();

bool PreProcessMsg(MSG &msg);

virtual void TileChildren(int tile = MDITILE_VERTICAL);

Protected Member Functions

void CmArrangeIcons();

void CmCascadeChildren();

void CmChildActionEnable(TCommandEnabler& commandEnabler);

void CmCloseChildren();

void CmCreateChild();

void CmTileChildren();

void CmTileChildrenHoriz();

LRESULT EvMDICreate(MDICREATESTRUCT far& createStruct);

void EvMDIDestroy(HWND hWnd);

char far *GetClassName();

Response Table Entries

EV_ macros and member functions


TMDIClient::Clie
TMDIClient::ClientAttr

Syntax

LPCLIENTCREATESTRUCT ClientAttr;

Description

ClientAttr holds a pointer to a structure of the MDI client window's attributes.


TMDIClient Public Constructor and Destructor
TMDIClient Public Constructors and Destructor

See Also

Constructor

TMDIClient(TModule* module = 0);

Description

Creates an MDI client window object by invoking the base class TWindow constructor, passing it a null parent window, a null title, and the specified library ID. Sets the default client window identifier (IDW_MDICLIENT) and sets the style to include MDIS_ALLCHILDSTYLES, WS_GROUP, WS_TABSTOP, WS_CLIPCHILDREN, WS_VSCROLL, and WS_HSCROLL. Initializes the ClientAttr data member, setting its idFirstChild member to IDW_FIRSTMDICHILD.

Destructor

~TMDIClient();

Description

Frees the ClientAttr structure.


See Also

TWindow::TWindow

TWindow::~TWindow


TMDIClient::ArrangeIcons

Syntax

virtual void ArrangeIcons();

Description

Arranges the MDI child window icons at the bottom of the MDI client window.


TMDIClient::CascadeChildren

Syntax

virtual void CascadeChildren();

Description

Sizes and arranges all of the non-iconized MDI child windows within the MDI client window. The children are overlapped, although each title bar is visible.


TMDIClient::CloseChildren

See Also

Syntax

virtual bool CloseChildren();

Description

First calls CanClose on each of the MDI child windows owned by this MDI client. Returns true if all MDI children are closed; otherwise returns false.


See Also

TWindow::CanClose


TMDIClient::CmArrangeIcons

See Also

Syntax

void CmArrangeIcons();

Description

Calls ArrangeIcons in response to a menu selection with an ID of CM_ARRANGEICONS.


See Also

TMDIClient::ArrangeIcons


TMDIClient::CmCascadeChildren

See Also

Syntax

void CmCascadeChildren();

Description

Calls CascadeChildren in response to a menu selection with an ID of CM_CASCADECHILDREN.


See Also

TMDIClient::CascadeChildren


TMDIClient::CmChildActionEnable

Syntax

void CmChildActionEnable(TCommandEnabler& commandEnabler);

Description

If there are MDI child windows, CmChildActionEnalbe enables any one of the child window action menu items.


TMDIClient::CmCloseChildren

See Also

Syntax

void CmCloseChildren();

Description

Calls CloseChildren in response to a menu selection with an ID of CM_CLOSECHILDREN.


See Also

TMDIClient::CloseChildren


TMDIClient::CmCreateChild

See Also

Syntax

void CmCreateChild();

Description

Calls CreateChild to produce a new child window in response to a menu selection with a menu ID of CM_CREATECHILD.


See Also

TMDIClient::CreateChild


TMDIClient::CmTileChildren

See Also

Syntax

void CmTileChildren();

Description

Calls TileChildren in response to a menu selection with an ID of CM_TILECHILDREN.


See Also

TMDIClient::TileChildren


TMDIClient::CmTileChildrenHoriz

Syntax

void CmTileChildrenHoriz();

Description

Calls TileChildren in response to a menu selection with an ID of CM_TILECHILDREN and passes MDI child tile flag as MDITILE_HORIZONTAL.


TMDIClient::Create

See Also

Syntax

Syntax

bool Create();

Description

Creates the interface element associated with the MDI client window. Calls TWindow::Create after first setting the child window menu in ClientAttr to the parent frame window's child menu.


See Also

TWindow_Create

TFrameWindow_GetMenuDescr


TMDIClient::CreateChild

See Also

Syntax

virtual TWindow* CreateChild();

Description

Overrides member function defined by TWindow. Constructs and creates a new MDI child window by calling InitChild and Create. Returns a pointer to the new MDI child window.


See Also

TMDIClient::InitChild

TModule::MakeWindow

TWindow::Create


TMDIClient::EvMDICreate

See Also

Syntax

LRESULT EvMDICreate(MDICREATESTRUCT far& createStruct);

Description

Intercepts the WM_MDICREATE message sent when MDI child windows are created, and, if the client's style includes MDIS_ALLCHILDSTYLES, and the child window's specified style is 0, then changes the child window style attributes to WS_VISIBLE, WS_CHILD, WS_CLIPSIBLINGS, WS_CLIPCHILDREN, WS_SYSMENU, WS_CAPTION, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX.


See Also

TWindow::DefaultProcessing

MDICREATE struct


TMDIClient::EvMDIDestroy

Syntax

void EvMDIDestroy(HWND hWnd);

Description

Intercepts the WM_MDIDESTROY message.


TMDIClient::GetActiveMDIChild

Syntax

TMDIChild *GetActiveMDIChild();

Description

GetActiveMDIChild points to the TMDIClient's active MDI child window. GetActiveMDIChild is set by the child in its EvMDIActivate message response member function. TMDIClient's constructors initialize GetActiveChild.


TMDIClient::GetClassName

Syntax

char far *GetClassName();

Description

Returns TMDIClient's registration class name, "MDICLIENT."


TMDIClient::InitChild

See Also

Syntax

virtual TMDIChild *InitChild();

Description

Constructs an instance of TWindow as an MDI child window and returns a pointer to it. Children must be created with MDI client as the parent window. Redefine this member function in your derived MDI window class to construct an instance of a derived MDI child class. For example,

PTWindowsObject TMyMDIClient::InitChild()

{

return new TMyMDIChild(this, "");

}


See Also

TMDIClient::CreateChild


TMDIClient::PreProcessMsg

See Also

Syntax

bool PreProcessMsg(MSG &msg);

Description

If the specified msg is one of WM_KEYDOWN or WM_SYSKEYDOWN, then the keyboard accelerators are translated for the MDI client.


See Also

TWindow::PreProcessMsg


TMDIClient::TileChildren

Syntax

virtual void TileChildren(int tile = MDITILE_VERTICAL);

Description

Sizes and arranges all of the non-iconized MDI child windows within the MDI client window. The children fill up the entire client area without overlapping.


TMDIClient::Response Table Entries
TMDIClient Response Table Entries

Response table entry	Member function

EV_COMMAND (CM_ARRANGEICONS, CmArrangeIcons)	CmArrangeIcons

EV_COMMAND (CM_CASCADECHILDREN, CmCascadeChildren)	CmCascadeChildren

EV_COMMAND (CM_CLOSECHILDREN, CmCloseChildren)	CmCloseChildren

EV_COMMAND (CM_CREATECHILD, CmCreateChild)	CmCreateChild

EV_COMMAND (CM_TILECHILDREN, CmTileChildren)	CmTileChildren

EV_COMMAND(CM_TILECHILDRENHORIZ,CmTileChildrenHoriz)	CmTileChildrenHoriz

EV_COMMAND_ENABLE(CM_TILECHILDREN, CmChildActionEnable)	CmChildActionEnable

EV_COMMAND_ENABLE(CM_CASCADECHILDREN, CmChildActionEnable)	CmChildActionEnable

EV_COMMAND_ENABLE(CM_ARRANGEICONS, CmChildActionEnable)	CmChildActionEnable

EV_COMMAND_ENABLE(CM_CLOSECHILDREN, CmChildActionEnable)	CmChildActionEnalbe

EV_WM_MDICREATE	EvMDICreate

EV_WM_MDIDESTROY	EvMDIDestroy


TMDIFrame Class

OWL Hierarchy	Inheritance

Header File

mdi.h

Description

Multiple Document Interface (MDI) frame windows, represented by TMDIFrame, are overlapped windows that serve as main windows of MDI-compliant applications. TMDIFrame objects automatically handle creating and initializing an MDI client window (represented by a TMDIClient object) required by Windows. TMDIFrame sets window style WS_CLIPCHILDREN by default so that minimal flicker occurs when the MDI frame erases its background and the backgrounds of its children. TMDIFrame is a streamable class.

Because TMDIFrame is derived from TFrameWindow, it inherits keyboard navigation. As a result, all children of the MDI frame acquire keyboard navigation. However, it's best to enable keyboard navigation only for those children who require it.

To create an OLE-enabled MDI frame window, use TOleMDIFrame, which inherits functionality from both TMDIFrame and TOleFrame.

Public Constructors

TMDIFrame(const char far *title, TResId menuResId, TMDIClient &clientWnd = *new TMDIClient, TModule* module = 0)

TMDIFrame(HWND hWindow, HWND clientHWnd, TModule* module = 0);

Public Member Functions

static HMENU FindChildMenu (HMENU newMenu);

TMDIClient *GetClientWindow ();

virtual HWND GetCommandTarget();

void PerformCreate (int menuOrId);

bool SetMenu (HMENU);

Protected Member Functions

LRESULT DefWindowProc (uint message, WPARAM wParam, LPARAM lParam);

Response Table Entries

EV_ macros and member functions


TMDIFrame Public Constructors

TMDIFrame

Form 1 Syntax

TMDIFrame(const char far *title, TResId menuResId, TMDIClient &clientWnd = *new TMDIClient, TModule* module = 0);

Description

Constructs an MDI frame window object using the caption (title) and resource ID (menuResId). If no client window is specified (clientWnd), then an instance of TMDIClient is created automatically and used as the client window of the frame. The supplied library ID (module) is passed to the TFrameWindow constructor along with a null parent window pointer, caption, client window, and a flag indicating that the client window is not to be resized to fit. The TWindow constructor is also invoked; it passes the supplied caption and library ID, as well as a null parent window pointer. Then the child menu position is initialized to be the leftmost menu item, and the supplied menu resource ID is used in a call to TFrameWindow::AssignMenu.

Form 2 Syntax

TMDIFrame(HWND hWindow, HWND clientHWnd, TModule* module = 0);

Description

Constructs an MDI frame window using an already created non-ObjectWindows window. Invokes the TFrameWindow and TWindow constructors, passing in the window handle (hWindow) and library ID (module). Initializes the child menu position to the leftmost menu item and constructs a TMDIClient object that corresponds to the supplied clientHWnd.


TMDIFrame::FindChildMenu

TMDIFrame

Syntax

static HMENU FindChildMenu(HMENU newMenu);

Description

FindChildMenu searches,  from right to left, the pop-up child menus contained in the newMenu menu resource for a child menu containing command items with one of the following identifiers: CM_CASCADECHILDREN, CM_TITLECHILDREN, or CM_ARRANGEICONS. The return value of FindChildMenu is the HMENU of the first child menu containing one of these identifiers. If one of these identifiers is not found, FindChildMenu returns 0.

FindChildMenu is used to locate the menu to which  the MDI child window list will be appended. This call to FindChildMenu is made from within the TMDIClient class.


TMDIFrame::GetClientWindow

See Also	TMDIFrame

Syntax

TMDIClient *GetClientWindow();

Description

Returns a pointer to the MDI client window.


See Also

TFrameWindow::GetClientWindow


TMDIFrame::GetCommandTarget

Syntax

virtual HWND GetCommandTarget();

Description

Locates and returns the child window that is the target of the command and the command enabling messages. If the current application does not have focus or if the focus is within a toolbar in the application, GetCommandTarget returns the most recently active child window. If an alternative form of command processing is desired, a user's main window class can override this function.


TMDIFrame::PerformCreate

TMDIFrame

Syntax

void PerformCreate(int menuOrId);

Description

Overrides TWindow's virtual PerformCreate function. Creates the interface element associated with the MDI frame window.


TMDIFrame::SetMenu

TMDIFrame

Syntax

bool SetMenu (HMENU);

Description

Searches for the MDI child menu in the new menu bar and updates the child menu position with the specified menu index. Then sends the client window an WM_MDISETMENU message to set the new menu and invokes TWindow::DrawMenuBar to redraw the menu. Returns false if the MDI client indicates that there was no previous menu; otherwise returns true.


TMDIFrame::DefWindowProc

TMDIFrame

Syntax

LRESULT DefWindowProc (uint message, WPARAM wParam, LPARAM lParam);

Description

Overrides TWindow::DefWindowProc and provides default processing for any incoming message the MDI frame window does not process.


TMDIFrame::Response Table Entries

TMDIFrame

The TMDIFrame response table has no entries.


TMeasurementUnits enum

OWL Hierarchy	See Also

Header File

layoutco.h

Syntax

enum TMeasurementUnits{lmPixels, lmLayoutUnits};

Description

Used by the TLayoutConstraint struct, TMeasurementUnits enumerates the measurement units (lmPixels or lmLayoutUnits) that control the dimension of the window. These can be either pixels or layout units that are obtained by dividing the font height into eight vertical and eight horizontal segments.


See Also

TLayoutConstraint struct


TMemoryDC Class

OWL Hierarchy	Inheritance

Header File

dc.h

Description

A device context (DC) class derived from TDC, TMemoryDC provides access to a memory DC.

Public Constructors

TMemoryDC();

TMemoryDC(const TDC& DC);

TMemoryDC(HDC handle, TAutoDelete autoDelete);

Public Member Functions

void RestoreBitmap();

void RestoreObjects();

void SelectObject(const TBrush& brush);

void SelectObject(const TPen& pen);

void SelectObject(const TFont& font);

void SelectObject(const TPalette& palette, bool forceBackground=false);

void SelectObject(const TBitmap& bitmap);

Protected Data Member

HBITMAP OrgBitmap;


TMemoryDC Public Constructors

See Also	TMemoryDC

Form 1

TMemoryDC();

Form 2

TMemoryDC(const TDC& DC);

Form 3

TMemoryDC(HDC handle, TAutoDelete AutoDelete);

Description

Form 1: Default constructor for a memory device context (DC) object.

Form 2: Creates a memory DC object compatible with the given DC argument.

Form 3: Creates a memory DC object from an existing DC handle.


See Also

TDC::TDC


TMemoryDC::RestoreBitmap

See Also	TMemoryDC

Syntax

void RestoreBitmap();

Description

Restores the originally selected bitmap object for this device context.


See Also

TDC::RestoreObjects


TMemoryDC::RestoreObjects

See Also	TMemoryDC

Syntax

void RestoreObjects();

Description

Restores the originally selected brush, pen, font, palette, and bitmap objects for this device context.


See Also

TDC::RestoreObjects

TMemoryDC::RestoreBitmap


TMemoryDC::SelectObject

See Also	TMemoryDC

Syntax

void SelectObject(const TBrush& brush);

void SelectObject(const TPen& pen);

void SelectObject(const TFont& font);

void SelectObject(const TPalette& palette, bool forceBackground=false);

void SelectObject(const TBitmap& bitmap);

Description

Selects the given GDI object into this DEVICE CONTEXT.


See Also

TDC::SelectObject

TMemoryDC::RestoreBitmap

TMemoryDC::RestoreObjects


TMemoryDC::OrgBitmap
TMemoryDEVICE CONTEXT::OrgBitmap

See Also	TMemoryDC

Syntax

HBITMAP OrgBitmap;

Description

The original bitmap selected into this device context.


See Also

TMemoryDC::SelectObject

TMemoryDC::RestoreBitmap


TMenu Class

OWL Hierarchy	Inheritance

Header File

menu.h

Description

The TMenu class encapsulates window menus. You can use TMenu member functions to construct, modify, query, and create menu objects. You can also use TMenu to add bitmaps to your menu or to specify if a menu item is checked or unchecked. TMenu includes two versions of a helper function,  DeepCopy , designed to make copies of menus and insert them at a specified position on the menu bar. See the ObjectWindows Programmer's Guide for information about how to create menu objects.

Public Constructors and Destructor

TMenu(TAutoDelete autoDelete = AutoDelete);

TMenu(HWND hWnd, TAutoDelete autoDelete = NoAutoDelete);

TMenu(const TMenu& original, TAutoDelete autoDelete = AutoDelete);

TMenu(HMENU handle, TAutoDelete autoDelete = NoAutoDelete);

TMenu(const void far* menuTemplate);

TMenu(HINSTANCE instance, TResId resId);

virtual ~TMenu();

Public Member Functions

bool AppendMenu(uint flags, uint newItem, const TBitmap& newBmp);

bool AppendMenu(uint flags, uint newItem = -1, const char far* newItem = 0);

bool CheckMenuItem(uint item, uint check);

void CheckValid(uint resId = IDS_MENUFAILURE);

bool DeleteMenu(uint item, uint flags);

virtual void DrawItem(DRAWITEMSTRUCT far& drawItem);

bool EnableMenuItem(uint item, uint enable);

virtual HMENU GetHandle(uint item, uint enable);

static bool GetMenuCheckMarkDimensions(TSize& size);

uint GetMenuItemCount() const;

uint GetMenuItemID(int posItem) const;

uint GetMenuState(uint item, uint flags) const;

uint GetMenuString(uint item, char* str, int count, uint flags) const;

HMENU GetSubMenu(int posItem) const;

bool InsertMenu(uint item, uint flags, uint newItem, const TBitmap& newBmp);

bool InsertMenu(uint item, uint flags, uint newItem = -1, const char far* newItem = 0);

bool IsOK() const;

virtual void MeasureItem(MEASUREITEMSTRUCT far& measureItem);

bool ModifyMenu(uint item, uint flags, uint newItem, const TBitmap& newBmp);

bool ModifyMenu(uint item, uint flags, uint newItem = -1, const char far* newItem = 0);

operator HMENU()const;

TMenu& operator =(const TMenu& original);

operator uint()const;

bool RemoveMenu(uint item, uint flags);

bool SetMenuItemBitmaps(uint item, uint flags, const TBitmap* bmpUnchecked=0, const TBitmap* bmpChecked=0);

Protected Data Members

HMENU Handle;

bool ShouldDelete;

Protected Member Functions

static void DeepCopy(TMenu& dest, const TMenu& source, int offset = 0, int count = -1);

static void DeepCopy(TMenu& dst, int dstOff, const TMenu& src, int srcOff = 0, int count = -1);


TMenu Public Constructors and Destructor

See Also	TMenu

Form 1

TMenu(TAutoDelete autoDelete = AutoDelete);

Form 2

TMenu(const TMenu& original, TAutoDelete autoDelete = NoAutoDelete);

Form 3

TMenu(HWND wnd, TAutoDelete autoDelete = NoAutoDelete);

Form 4

TMenu(HMENU handle, TAutoDelete autoDelete = NoAutoDelete);

Form5

TMenu(const void far* menuTemplate);

Form 6

TMenu(HINSTANCE instance, TResId resId);

Form 7

virtual ~TMenu();

Description

Form 1: Creates an empty menu and sets autoDelete, by default, so that the menu is automatically deleted when the object is destroyed.

Form2: Creates a complete copy of an existing menu and sets autoDelete, by default, so that the menu is not automatically deleted when the object is destroyed.

Form3: Creates a menu object representing the window's current menu and sets autoDelete, by default, so that the menu is not automatically deleted when the object is destroyed.

Form 4: Creates a menu object from an already loaded menu and sets autoDelete, by default, so the menu is not automatically deleted when the object is destroyed.

Form 5: Creates a menu object from a menu template in memory. This constructor is not available under Presentation Manager.

Form 6: Creates a menu object from a specified resource ID.

Destructor

Destroys the menu.


See Also

TResId


TMenu::AppendMenu

See AlsoTMenu

Form 1

bool AppendMenu(uint flags, uint newItem, const TBitmap& newBmp);

Form 2

bool AppendMenu(uint flags, uint newItem = -1, const char far* newItem = 0);

Description

Form 1: Adds a bitmap menu item at the end of the menu. See TMenu::GetMenuState for a description of the flag values that specify the attributes of the menu, for example, menu item is checked, menu item is disabled, and so on.

Form 2: Adds a text menu item to the end of the menu.  See TMenu::GetMenuState for a description of the flag values that specify the attributes of the menu, for example, menu item is checked, menu item is a a bitmap, and so on.


See Also

TBitmap

TMenu::GetMenuState


TMenu::CheckMenuItem

TMenu

Syntax

bool CheckMenuItem(uint item, uint check);

Description

Checks or unchecks the menu item. By combining flags with the bitwise OR operator (|) check specifies both the position of item (MF_BYCOMMAND, MF_BYPOSITION) and whether item is to be checked (MF_CHECKED) or unchecked (MF_UNCHECKED).


TMenu::CheckValid

See Also	TMenu

Syntax

void CheckValid(uint resId = IDS_MENUFAILURE);

Description

Throws a TXMenu exception if the menu object is invalid.


See Also

TMenu::TXMenu


TMenu::DeleteMenu

See Also	TMenu

Syntax

bool DeleteMenu(uint item, uint flags);

Description

Removes the menu item (item) from the menu or deletes the menu item if it's a pop-up menu. flags is used to identify the position of the menu item by its relative position in the menu (MF_BYPOSITION) or by referencing the handle to the top-level menu (MF_BYCOMMAND).


See Also

TMenu::RemoveMenu


TMenu::DrawItem

See Also	TMenu

Syntax

virtual void DrawItem(DRAWITEMSTRUCT far& drawItem);

Description

DrawItem responds to a message forwarded to a drawable control by TWindow when the control needs to be drawn.


See Also

DRAWITEMSTRUCT struct


TMenu::EnableMenuItem

TMenu

Syntax

bool EnableMenuItem(uint item, uint enable);

Description

Enables, disables, or grays the menu item specified in the item parameter. If a menu item is enabled (the default state), it can be selected and used as usual. If a menu item is grayed, it appears in grayed text and cannot be selected by the user. If a menu item is disabled, it is not displayed. Returns true if successful.


TMenu::GetHandle

See Also	TMenu

Syntax

virtual HMENU GetHandle();

Description

Returns the handle to the menu.


See Also

TMenu::IsOK


TMenu::GetMenuCheckMarkDimensions

See Also	TMenu

Syntax

static bool GetMenuCheckMarkDimensions(TSize& size);

Description

Gets the size of the bitmap used to display the default check mark on checked menu items.


See Also

TMenu::SetMenuItemBitmaps

TSize


TMneu::GetMenuItemCount
TMenu::GetMenuItemCount

TMenu

Syntax

uint GetMenuItemCount() const;

Description

Returns the number of items in a top-level or pop-up menu.


TMenu::GetMenuItemID

TMenu

Syntax

uint GetMenuItemID(int posItem) const;

Description

Returns the ID of the menu item at the position specified by posItem. If the menu is a pop-up menu, GetMenuItemID returns the ID of the menu's first item minus one.


TMenu::GetMenuState

TMenu

Syntax

uint GetMenuState(uint item, uint flags) const;

Description

Returns the menu flags for the menu item specified by item. flags specifies how the item is interpreted, and is one of the following values:

Flag	Description

MF_BYCOMMAND	Interpret item as a menu command ID. Default it neither MF_BYCOMMAND nor MF_BYPOSITION is specified.

MF_BYPOSITION	Interpret item as the zero-base relative postion of the menu item within the menu.

If item is found, and is a pop-up menu, the low-order byte of the return value contains the flags associated with item, and the high-order byte contains the number of items in the pop-up menu. If itemis not a pop-up menu, the return value specifies a combination of these flags:

Flag	Description

MF_BITMAP	Menu item is a a bitmap.

MF_CHECKED	Menu item is checked (pop-up menus only).

MF_DISABLED	Menu item is disabled.

MF_ENABLED	Menu item is enabled. Note: this constant's value is 0.

MF_GRAYED	Menu item is disabled and grayed.

MF_MENUBARBREAK	Same as MF_MENUBREAK except pop-up menu columns are separated by a vertical dividing line.

MF_MENUBREAK	Static menu items are placed on a new line, pop-up menu items are placed in a new column, without separating columns.

MF_SEPARATOR	A horizontal dividing line is drawn, which cannot be enabled, checked, grayed, or highlighted. Both item and flags are ingonred.

MF_UNCHECKED	Menu item check mark is removed (default). Note: this constant value is 0.

Returns -1 if item doesn't exist.


TMenu::GetMenuString

TMenu

Syntax

uint GetMenuString(uint item, char* str, int count, uint flags) const;

Description

Returns the label (str) of the menu item (item).


TMenu::GetSubMenu

TMenu

Syntax

HMENU GetSubMenu(int posItem) const;

Description

Returns the handle of the menu specified by posItem.


TMenu::InsertMenu

See Also	TMenu

Form 1

bool InsertMenu(uint item, uint flags, uint newItem, const TBitmap& newBmp);

Form 2

bool InsertMenu(uint item, uint flags, uint newItem = -1, const char far* newItem = 0);

Description

Form 1: Adds a bitmap menu item after the menu item specified in item. The flags parameter contains either the MF_BYCOMMAND or MF_BYPOSITION values that indicate how to interpret the item parameter. If MF_BYCOMMAND, item is a command ID; if MF_BYPOSITION, item holds a relative position within the menu.

Form 2: Inserts a new text menu item or pop-up menu into the menu after the menu item specified in item. The flagsparameter contains either the MF_BYCOMMAND or MF_BYPOSITION values that indicate how to interpret the item parameter. If MF_BYCOMMAND, item is a command ID; if MF_BYPOSITION, item holds a relative position within the menu.


See Also

TMenu::GetMenuState


TMenu::IsOK

See Also	TMenu

Syntax

bool IsOK() const;

Description

Returns true if the menu has a valid handle.


See Also

TMenu::GetHandle


TMenu::MeasureItem

See Also	TMenu

Syntax

virtual void MeasureItem(MEASUREITEMSTRUCT far& measureItem);

Description

measureItem is used by owner-drawn controls to store the dimensions of the specified item.


See Also

MEASUREITEMSTRUCT struct


TMenu::ModifyMenu

See Also	TMenu

Form 1

bool ModifyMenu(uint item, uint flags, uint newItem, const TBitmap& newBmp);

Form 2

bool ModifyMenu(uint item, uint flags, uint newItem = -1, const char far* newItem = 0);

Description

Form 1: Changes an existing menu item into a bitmap. The flags parameter contains either the MF_BYCOMMAND or MF_BYPOSITION values that indicate how to interpret the item parameter. If MF_BYCOMMAND, item is a command ID; if MF_BYPOSITION, item holds a relative position within the menu.

Form 2: Changes an existing menu item from the item specified in item to newItem. The flags parameter contains either the MF_BYCOMMAND or MF_BYPOSITION values that indicate how to interpret the item parameter. If MF_BYCOMMAND, item is a command ID; if MF_BYPOSITION, item holds a relative position within the menu.


See Also

TMenu::GetMenuState


TMenu::operator HMENU

See Also	TMenu

Syntax

operator HMENU()const;

Description

Returns the menu's handle.


See Also

TMenu::operator uint


TMenu::operator =

See Also	TMenu

Syntax

TMenu& operator =(const TMenu& original);

Description

Returns the TMenu object.


See Also

TMenu::operator uint


TMenu::operator uint

See Also	TMenu

Syntax

operator uint()const;

Description

Returns the menu's handle. This function provides compatibility with functions that require a uint menu parameter.


See Also

TMenu::operator HMenu


TMenu::RemoveMenu

See Also	TMenu

Syntax

bool RemoveMenu(uint item, uint flags);

Description

Removes the menu item from the menu but does not delete it if it is a sub-menu.


See Also

TMenu::DeleteMenu


TMenu::SetMenuItemBitmaps

See Also	TMenu

Syntax

bool SetMenuItemBitmaps(uint item, uint flags, const TBitmap* bmpUnchecked=0, const TBitmap* bmpChecked=0);

Description

Specifies the bitmap to be displayed when the menu item is checked and unchecked. item indicates the menu item to be associated with the bitmap. flags indicates how the size parameter is interpreted (whether by MF_BYPOSITION or by MF_BYCOMMAND). GetMenuCheckMarkDimensions gets the size of the bitmap.


See Also

TMenu::GetMenuCheckmarkDimensions

TBitmap


TMenu::Handle

TMenu

Syntax

HMENU Handle;

Description

Holds the handle to the menu.


TMenu::ShouldDelete

See Also	TMenu

Syntax

bool ShouldDelete;

Description

ShouldDelete is set to true if the Destructor needs to delete the handle to the menu.


See Also

TMenu::DeleteMenu

TMenu::RemoveMenu


TMenu::DeepCopy

Form 1

static void DeepCopy(TMenu& dest, const TMenu& source, int offset = 0, int count = -1);

Form 2

static void DeepCopy(TMenu& dst, int dstOff, const TMenu& src, int srcOff = 0, int count = -1);

Description

Form 1

Makes a deep copy (that is, an actual copy of the menu, not just a copy of pointers or handles to a menu) of the menu. This form of  DeepCopy  copies count number of pop-up menus or menu items from src beginning at offset  and appends the items or menus to the destination menu. If count is passed as -1, all source menu items are copied.

Form 2

Makes a deep copy (that is, an actual copy of the menu, not just a copy of pointers or handles to a menu) of the menu. This form of  DeepCopy  copies count number of pop-up menus or menu items from source beginning at offset and inserts the items or menus at the  dstOffset position specified in the destination menu (dest). If count is passed as -1, all source menu items are copied.


TMenuDescr Class

See Also	OWL Hierarchy	Inheritance

Header File

menu.h

Description

Derived from TMenu, TMenuDescr describes your menu bar and its functional groups. TMenuDescr provides an easy way for you to group menus on your menu bar and to add new groups to an existing menu bar. It uses a resource ID to identify the menu resource and an array of count values to indicate the number of pop-up menus in each group on the menu bar.

The TGroup enum enumerates the six basic functional groups on a menu bar: File, Edit, Container, Object, Window, and Help. TMenuDescr's constructors simply initialize the members based on the arguments passed.  TFrameWindow::MergeMenu actually performs the real work of merging the menu groups.

For a single document application (SDI), the menus are merged as soon as you load the application. However, for a multiple-document application (MDI), you do not see the final menu until you invoke a child menu. See the sample program, mdifile.cpp, for an example of MDI menu merging.

One technique you can use to create a menu involves invoking the TMenuDescr constructor and passing the number of group counts for each menu selection.

For example, if your original menu groups included these items:

you might use the following group counts:

Group	Count	Menu

FileGroup	1	File

EditGroup	2	Edit Search

ContainerGroup	1	View

ObjectGroup	3	Page Paragraph Word

WindowGroup	1	Window

HelpGroup	1	Help

You would then invoke the constructor this way:

TMenuDescr(IDM_MYMENU, 1, 2, 1, 3, 1, 1)

You can build the previous menu by merging two menus. When a zero is passed in the parent menu's constructor, the group indicated by the zero is filled in by the child menu's group, if an item is specified, when the menu merging occurs.  Set your application's parent frame menu bar by specifying these menu groups:

and passing these group counts in the constructor:

TMenuDescr(IDM_FRAME, 1, 0, 1, 0, 1, 1)

Set the word-processor child menu bar this way:

and pass these values in the constructor:

TMenuDescr(IDM_WPROC, 0, 2, 0, 3, 0, 1)

If no child is active, only the frame menu will be active. When the word processor's child window becomes active, the child menu bar is merged with the frame menu. Every group that is 0 in the child menu bar leaves the parent's group intact. The previous example interleaves every group except for the last group, the Help group, in which the child replaces the frame menu.

By convention, the even groups (File, Container, Window) usually belong to the outside frame or container, and the odd groups (Edit, Object, Help) belong to the child or contained group.

If a -1 is used in a group count, the merger eliminates the parent's group without replacing it. For example, another child menu bar, such as a calculator, could be added to your application in this way:

TMenuDescr(IDM_WCALC, 0, 1, -1, 1, 0, 1)

In this example, the child's menu group contributes nothing from the container group, and the parent's container group is removed. This produces a merged menu (with the View menu selection eliminated as a result of the -1) that looks like this:

If you want to merge the following parent menu groups

with these paint window menu groups,

pass the following group counts in the constructor:

TMenuDescr(IDM_WPAINT, 0, 1, 0, 2, 0, 1)

This produces the following merged menu:

The simplest way to add groups to a menu bar involves defining the menu groups and adding separators in a resource file. Insert the term MENUITEM SEPARATOR between each menu group and an additional separator if one of the menu groups is not present. For example, the resource file for Step 14 of the ObjectWindows tutorial defines the following menu groups and separators:

IDM_MDICMNDS MENU

{

// Display a grayed File menu

 MENUITEM "File",   0,GRAYED  ;placeholder for File menu from DocManager

 MENUITEM SEPARATOR

 MENUITEM "Edit",   CM_NOEDIT ;placeholder for Edit menu from View

 MENUITEM SEPARATOR

 MENUITEM SEPARATOR

 MENUITEM SEPARATOR

 POPUP "&Window"

{

// Options within the Window menu group

  MENUITEM  "&Cascade",       CM_CASCADECHILDREN

  MENUITEM  "&Tile",          CM_TILECHILDREN

  MENUITEM  "Arrange &Icons", CM_ARRANGEICONS

  MENUITEM  "C&lose All",     CM_CLOSECHILDREN

  MENUITEM  "Add &View",      CM_VIEWCREATE

 }

 MENUITEM SEPARATOR

 POPUP "&Help"

 {

  MENUITEM "&About",   CM_ABOUT

 }

}

You can see the separators by loading Step14.rc into Resource Workshop and disabling the View as Popup Option in the View menu. This resource file defines an Edit group, a File group, a Window group, and a Help group, but no entries for Container or Object groups.

Step14.cpp uses these commands from the resource file to set the main window and its menu, passing IDM_MDICMNDS as the parameter to SetMenuDescrfunction, as follows:

SetMainWindow(frame);

GetMainWindow()->SetMenuDescr(TMenuDescr(IDM_MDICMNDS));

It produces the following menu groups:

TMenuDescr's functions let you perform menu merging similar to that of OLE 2. That is, you can merge menus from a container's document (the MDI frame window) with those of an embedded object (the MDI child window). When the embedded object is activated in place by double-clicking the mouse, the menu of the child window merges with that of the frame window.

Public Constructors and Destructor

TMenuDescr();

TMenuDescr(const TMenuDescr& original);

TMenuDescr(TResId id, TModule* module = ::Module);

TMenuDescr(TResId id, int fg, int eg, int cg, int og, int wg, int hg, TModule* module = ::Module);

TMenuDescr(HMENU hMenu, int fg, int eg, int cg, int og, int wg, int hg, TModule* module = ::Module);

~TMenuDescr();

Type Definitions

enum TGroup{ FileGroup, EditGroup, ContainerGroup, ObjectGroup, WindowGroup, HelpGroup, NumGroups};

Public Member Functions

HMENU GetHandle() const ;

TModule* GetModule() const;

void SetModule(TModule* module);

TResId GetId() const;

int GetGroupCount(int group) const;

void ClearServerGroupCount();

void ClearContainerGroupCount();

bool Merge(const TMenuDescr& sourceMenuDescr);

bool Merge(const TMenuDescr& sourceMenuDescr, TMenu& destMenu);

Protected Data Members

TResId Id;

int GroupCount[NumGroups];

TModule* Module;

Protected Member Functions

bool ExtractGroups();


See Also

TMenu

TOcMenuDescr


TMenuDescr::Id

TMenuDescr

Syntax

TResId Id;

Description

The resource ID for the menu. The resource ID is passed in the constructors to identify the menu resource.


TMenuDescr::GroupCount

See Also	TMenuDescr

Syntax

int GroupCount[NumGroups];

Description

An array of values indicating the number of pop-up menus in each group on the menu bar.


See Also

TGroup enum


TMenuDescr::Module

TMenuDescr

Syntax

TModule* Module

Description

Points to the TModule object that owns this TMenuDescr.


TMenuDescr Public Constructors and Destructor

TMenuDescr

Syntax

TMenuDescr();

Description

Default constructor for a TMenuDescr object. No menu resources or groups are specified. Constructs an empty menu bar.

Syntax 1

TMenuDescr(TResId id, int fg, int eg, int cg, int og, int wg, int hg, TModule* module = ::Module);

Description

Constructs a menu descriptor from the resource indicated by id. Places the pop-up menus in groups according the values of the fg, eg, cg, of, wg, and hg parameters. The fg, eg, cg, of, wg, and hg parameters represent the functional groups identified by the TGroup enum. Calls the function ExtractGroups to extract the group counts based on the separator items in the menu bar.

Syntax 2

TMenuDescr(const TMenuDescr& original);

Description

Copies the menu descriptor object specified in the original parameter.

Syntax 3

TMenuDescr(TResId id, TModule* module = ::Module);

Description

Creates a menu descriptor from the menu resource specified in the id parameter. Calls the function ExtractGroups to extract the group counts based on the separator items in the menu bar.

Syntax 4

TMenuDescr(HMENU hMenu, int fg, int eg, int cg, int og, int wg, int hg, TModule* module = ::Module);

Description

Constructs a menu descriptor from the menu handle indicated in the hMenu parameter. The menu descriptor can have zero or more pop-up menus in more than one functional group. The fg, eg, cg, of, wg, and hg parameters represent the functional groups identified by the TGroup enum.  Calls the function ExtractGroups to extract the group counts based either on the separator items in the menu bar or on the group count parameters specified if there are no separators in the menu bar.

Destructor Syntax

~TMenuDescr();

Description

Destroys the TMenuDescr object.


TMenuDescr::ExtractGroups

Syntax

bool ExtractGroups();

Description

 Extracts the group counts from the loaded menu bar by counting the number of menus between separator items. After the group counts are extracted, the separators are removed.


TGroup enum
TMenuDescr::TGroup enum

See Also	TMenuDescr

Syntax

enum TGroup{FileGroup, EditGroup, ContainerGroup, ObjectGroup, WindowGroup, HelpGroup, NumGroups};

Description

Used by TMenuDescr, the TGroup enum describes the following constants that define the index of the entry in the GroupCount array.

Constant	Meaning

FileGroup	Index of the File menu group count

EditGroup	Index of the Edit menu group count

ContainerGroup	Index of the Container menu group count

ObjectGroup	Index of the Object group count

WindowGroup	Index of the Window menu group count

HelpGroup	Index of the Help menu group count

NumGroups	Total number of groups


See Also

TMenuDescr::GroupCount


TMenuDescr::GetHandle

TMenuDescr

Syntax

HMENU GetHandle() const;

Description

Gets the handle to the menu, possibly causing any deferred menu acquisition to occur.


TMenuDescr::GetModule

TMenuDescr

Syntax

TModule* GetModule() const;

Description

Returns a pointer to the module object.


TMenuDescr::SetModule

TMenuDescr

Syntax

void SetModule(TModule* module);

Description

Sets the default module object for this menu descriptor.


TMenuDescr::GetId

TMenuDescr

Syntax

TResId GetId() const;

Description

Gets the menu resource ID used to construct the menu descriptor.


TMenuDescr::GetGroupCount

TMenuDescr

Syntax

int GetGroupCount(int group) const;

Description

Gets the number of menus in a specified group within the menu bar. There are a maximum of six functional groups as defined by the TGroup enum. These groups include FileGroup,  EditGroup, ContainerGroup, ObjectGroup, WindowGroup, and HelpGroup.


TMenuDescr::ClearServerGroupCount

See Also	TMenuDescr

Syntax

void ClearServerGroupCount();;

Description

Clears the odd groups (that is, 1, 3, 5 or Edit Group, Object Group, and Help Group) in the menu bar for a server application.


See Also

TGroup enum

TOcMenuDescr


TMenuDescr::ClearContainerGroupCount

See Also	TMenuDescr

Syntax

void ClearContainerGroupCount();

Description

Clears the even groups (that is, 0, 2, 4 or File Group, Container Group, Window Group) in the menu bar for a container application.


See Also

TGroup enum

TOcMenuDescr


TMenuDescr::Merge

See Also	TMenuDescr

Syntax 1

bool Merge(const TMenuDescr& sourceMenuDescr);

Description

Merges the functional groups of another menu descriptor into this menu descriptor.

Syntax 2

bool Merge(const TMenuDescr& sourceMenuDescr, TMenu& destMenu);

Description

Merges the functional groups of this menu descriptor and another menu descriptor into an empty menu.


See Also

TMenuDesc::TGroup enum


TMenuItemEnabler Class

OWL Hierarchy	Inheritance

Header File

framewin.h

Derived from TCommandEnabler, TMenuItemEnabler is a command enabler for menu items. The functions in this class modify the text, check state, and appearance of a menu item.

Public Constructors

TMenuItemEnabler(HMENU hMenu, uint id, HWND hWndReceiver, int position);

Protected Data Member

HMENU HMenu;

int Position;

Public Member Functions

void Enable(bool enable);

HMENU GetMenu();

int GetPosition();

void SetText(LPCSTR);

void SetCheck(int state);


TMenuItemEnabler Public Constructors
TMenuItemEnabler Public Constructor

TMenuItemEnabler

Syntax

TMenuItemEnabler(HMENU hMenu, uint id, HWND hWndReceiver, int position);

Description

Constructs a TMenuItemEnabler with the specified command ID, for the menu item, message responder (hWndReceiver), and position on the menu.


TMenuItemEnabler::HMenu

TMenuItemEnabler

Syntax

HMENU HMenu;

Description

The menu that holds the item being enabled or disabled.


TMenuItemEnabler::Position

TMenuItemEnabler

Syntax

int Position;

Description

The position of the menu item.


TMenuItemEnabler::Enable

TMenuItemEnabler

Syntax

void Enable(bool enable);

Description

Overrides TCommandEnable::Enable. Enables or disables the menu options that control the appearance of the corresponding menu item.


TMenuItemEnabler::GetMenu

TMenuItemEnabler

Syntax

HMENU GetMenu();

Description

Returns the menu that holds the item being enabled or disabled.


TMenuItemEnabler::GetPosition

TMenuItemEnabler

Syntax

int GetPosition();

Description

Returns the position of the menu item.


TMenuItemEnabler::SetText

TMenuItemEnabler

Syntax

void SetText(LPCSTR);

Description

Overrides TCommandEnable::SetText. Changes the text of the corresponding menu item.


TMenuItemEnabler::SetCheck

TMenuItemEnabler

Syntax

void SetCheck(int state);

Description

Overrides TCommandEnable::SetCheck. Checks or unchecks the corresponding menu item. The state parameter reflects the menu item's state, which can be checked, unchecked, or indeterminate.


TMessageBar Class

OWL Hierarchy	Inheritance

Header File

messageb.h

Description

Derived from TGadgetWindow, TMessageBar implements a message bar with one text gadget as wide as the window and no border. Normally positioned at the bottom of the window, the message bar uses the default gadget window font and draws a highlighted line at the top.

Public Constructor

TMessageBar(TWindow* parent = 0, TFont* font = new TGadgetWindowFont, TModule* module = 0);

Public Member Functions

virtual void SetHintText(const char* text);

void SetText(const char* text);

Protected Data Members

bool HighlightLine;

char* HintText;

Protected Member Functions

void GetDesiredSize(TSize& rect);

void GetInnerRect(TRect& rect);

void PaintGadgets(TDC& dc, bool erase, TRect& rect);


TMessageBar Public Constructor

See Also	TMessageBar

Syntax

TMessageBar(TWindow* parent = 0, TFont* font = new TGadgetWindowFont, TModule* module = 0);

Description

Constructs a TMessageBar object with the gadget window font. Sets IDW_STATUSBAR, HighlightLine to true, and TTextGadget's member WideAsPossible to true, making the text gadget as wide as the window.


See Also

TGadgetWindowFont::TGadgetWindowFont


TMessageBar::SetHintText

TMessageBar

Syntax

virtual void SetHintText(const char* text);

Description

Sets or clears the menu hint text for the message bar. Hint text is displayed over all other gadgets and is used for menu and control bar button help.


TMessageBar::SetText

See Also	TMessageBar

Syntax

void SetText(const char* text);

Description

Forwards the message in the message bar to the text gadget for formatting.


See Also

TTextGadget::SetText


TMessageBar::HighlightLine

TMessageBar

Syntax

bool HighlightLine;

Description

Is true if a highlighted line is drawn.


TMessageBar::HintText

TMessageBar

Syntax

char* HintText;

Description

Stores the command hint text, if any, that's currently being displayed.


TMessageBar::GetDesiredSize

See Also	TMessageBar

Syntax

void GetDesiredSize(TSize& rect);

Description

Calls TGadgetWindow's GetDesiredSize to get the size of the message bar. Then, if a highlighting line is drawn, adjusts the size of the message bar.


See Also

TGadgetWindow::GetDesiredSize


TMessageBar::GetInnerRect

See Also	TMessageBar

Syntax

void GetInnerRect(TRect& rect);

Description

GetInnerRect computes the rectangle inside the borders and margins of the message bar.


See Also

TGadgetWindow::GetInnerRect


TMessageBar::PaintGadgets

See Also	TMessageBar

Syntax

void PaintGadgets(TDC& dc, bool erase, TRect& rect);

Description

Adjusts the message bar and paints a highlight line. Then, PaintGadgets either paints the hint text if any is set or calls TGadgetWindow::PaintGadgets to repaint each gadget.


See Also

TGadgetWindow::PaintGadgets


TMetaFileDC Class

OWL Hierarchy	Inheritance

Header File

dc.h

Description

Derived from TDC, TMetaFileDC provides access to a device context with a metafile selected for drawing.

Public Constructor and Destructors

TMetaFileDC(const char far* filename = 0);

~TMetaFileDC();

Public Member Function

HMETAFILE Close();


TMetaFileDC Public Constructors and Destructor
TMetaFileDC Public Constructor and Destructor

See Also	TMetaFileDC

Syntax

TMetaFileDC(const char far* filename = 0);

Destructor

~TMetaFileDC();

Description

Creates a TMetaFileDC object with the data written to the named file if one is provided.

Destructor: Destroys this object.


See Also

TDC::TDC


TMetaFileDC::Close

See Also	TMetaFileDC

Syntax

HMETAFILE Close();

Description

Closes this metafile DC object. Sets the Handle data member to 0 and returns a pointer to a new TMetaFilePict object.


See Also

TMetaFilePict


TMetaFilePict class

OWL Hierarchy

Header File

metafile.h

Description

TMetaFilePict is a support class used with TMetaFileDC to simplify metafile operations, such as playing into a device context (DC) or storing data on the clipboard. TMetaFilePict automatically handles the conversion between a metafile and a metafilepict.

Public constructors and destructor

TMetaFilePict(HMETAFILE handle, TAutoDelete autoDelete);

TMetaFilePict(const TClipboard& clipboard);

TMetaFilePict(const char* filename);

TMetaFilePict(uint size, void far* data);

TMetaFilePict(HGLOBAL data);

TMetaFilePict(const TMetaFilePict& orig, const char far* fileName = 0);

~TMetaFilePict()

Public member functions

TSize CalcPlaySize(TDC& dc, const TSize& defSize) const;

HANDLE GetMetaFileBits();

uint32 GetMetaFileBitsEx(uint size, void* data);

int Height() const;

operator HMETAFILE() const;

TClipboard& operator <<(TClipboard& clipboard, TMetaFilePict& mfp);

unsigned MappingMode()const;

bool PlayOnto(TDC& dc, const TSize& defSize) const;

void SetMappingMode(unsigned mm);

void SetSize(const TSize& size);

TSize Size() const;

void ToClipboard(TClipboard& clipboard, unsigned mapMode = MM_ANISOTROPIC, const TSize& extent=TSize(0,0));

int Width() const;

Protected data members

TSize Extent;

int Mm;


TMetaFilePict Public Constructors and Destructor

See Also	TMetaFilePict

Syntax 1

TMetaFilePict(HMETAFILE handle, TAutoDelete autoDelete);

Description

Creates a TMetaFilePict object using the given handle argument.

Syntax 2

TMetaFilePict(const TClipboard& clipboard);

Description

Creates a TMetaFilePict object from the contents of the specified clipboard.

Syntax 3

TMetaFilePict(const char* filename);

Description

Creates a TMetaFilePict object for the metafile stored in the named file.

Syntax 4

TMetaFilePict(uint size, void far* data);

Description

Creates a TMetaFilePict object for the memory-based metafile specified by data. The data buffer must hold a metafile of length size bytes.

Syntax 5

TMetaFilePict(HGLOBAL data);

Description

Creates a TMetaFilePict object for the memory-based metafile specified by data. The data global memory block must hold a  metafile.

Syntax 6

TMetaFilePict(const TMetaFilePict& orig, const char far* fileName = 0);

Description

Copies the metafile orig to the named file. If filename is 0 (the default), the metafile is copied to a memory-based metafile.

Destructor

~TMetaFilePict()

Description

Destroys this object.


See Also

TClipboard


TMetaFilePict::GetMetaFileBits

TMetaFilePict

Syntax

HANDLE GetMetaFileBits();

Description

Returns a handle to a global memory block containing this metafile as a collection of bits. The memory block can be used to determine the size of the metafile or to save the metafile as a file.


TMetaFilePict::GetMetaFileBitsEx

TMetaFilePict

Syntax

uint32 GetMetaFileBitsEx(uint size, void* data);

Description

(32-bit only) Retrieves the contents of the metafile associated with this object and copies them (up to size bytes) to the data buffer. If data is nonzero and the call succeeds, the actual number of bytes copied is returned. If data is 0, a successful call returns the number of bytes required by the buffer. A return value of 0 always indicates a failure.


TMetaFilePict::Height

TMetaFilePict

Syntax

int Height() const;

Description

Retrieves the height of this metafile.


TMetaFilePict::MappingMode

TMetaFilePict

Syntax

unsigned MappingMode()const;

Description

Retrieves the mapping mode of this metafile.


TMetaFilePict::operator HMETAFILE()

TMetaFilePict

Syntax

operator HMETAFILE() const;

Description

Type-conversion operator.


TMetaFilePict::operator <<

See Also	TMetaFilePict

Syntax

TClipboard& operator <<(TClipboard& clipboard, TMetaFilePict& mfp);

Description

Places the TMetaFilePict object onto the Clipboard. Returns a reference to the resulting Clipboard, allowing the usual chaining of << operations.


See Also

TClipboard


TMetaFilePict::PlayOnto

See Also	TMetaFilePict

Syntax

bool PlayOnto(TDC& dc, const TSize& defSize) const;

Description

Plays the metafile into a device context.


See Also

TDC

TSize


TMetaFilePict::SetMappingMode

TMetaFilePict

Syntax

void SetMappingMode(unsigned mm);

Description

Sets the mapping mode of this metafile.


TMetaFilePict::SetSize

TMetaFilePict

Syntax

void SetSize(const TSize& size);

Description

Sets the size of this metafile.


TMetaFilePict::Size

TMetaFilePict

Syntax

TSize Size() const;

Description

Retrieves the size of this metafile.


TMetaFilePict::CalcPlaySize

See Also	TMetaFilePict

Syntax

TSize CalcPlaySize(TDC& dc, const TSize& defSize) const;

Description

Calculates the size of this metafile when played on a given DC.


See Also

TDC

TSize


TMetaFilePict::ToClipboard

See Also	TMetaFilePict

Syntax

void ToClipboard(TClipboard& clipboard, unsigned mapMode = MM_ANISOTROPIC, const TSize& extent=TSize(0,0));

Description

Puts this metafile onto the Clipboard.


See Also

TClipboard

TSize


TMetaFilePict::Width

TMetaFilePict

Syntax

int Width() const;

Description

Retrieves the width of this metafile.


TMetaFilePict::Extent

TMetaFilePict

Syntax

TSize Extent;

Description

Holds the extent or size of the metafile.


TMetaFilePict::Mm

TMetaFilePict

Syntax

int Mm;

Description

Stores the mapping mode for the metafile.


TModule Class

OWL Hierarchy	Inheritance

Header File

module.h

Description

ObjectWindows dynamic-link libraries (DLLs) construct an instance of TModule, which acts as an object-oriented stand-in for the library (DLL) module. TModule defines behavior shared by both library and application modules. ObjectWindows applications construct an instance of TApplication, derived from TModule. TModule's constructors manage loading and freeing of external DLLs, and the member functions provide support for default error handling.

Public Data Members

char far* lpCmdLine;

extern TModule *Module;

TStatus Status;

Public Constructors and Destructor

TModule(const char far* name, HINSTANCE hInstance, const char far* cmdLine);

TModule(const char far* name, HINSTANCE hInstance);

TModule(const char far* name, bool shouldLoad = true);

~TModule();

Public Member Functions

int AccessResource(HRSRC hRsrc) const;

HGLOBAL AllocResource(HRSRC hRsrc, uint32 size) const;

HCURSOR CopyCursor(HCURSOR hCursor) const;

HICON CopyIcon(HICON hIcon) const;

virtual void Error(int errorCode);

virtual int Error(xmsg& x, unsigned captionResId, unsigned promptResId=0);

int ExecDialog(TDialog* dialog);

HRSRC FindResource(TResId id, const char far* type) const;

HWND GetClientHandle(HWND hWnd);

bool GetClassInfo(const char far* name, WNDCLASS far* wndclass) const;

HINSTANCE GetInstance() const;

int GetInstanceData(void* data, int len) const;

int GetModuleFileName(char far* buff, int maxChars);

int GetModuleUsage() const;

const char far* GetName() const;

TWindow* GetParentObject(HWND hWndParent);

FARPROC GetProcAddress(const char far* fcnName) const;

void InitModule(HINSTANCE hInstance, const char far* cmdLine);

bool IsLoaded() const;

HACCEL LoadAccelerators(TResId id) const;

HBITMAP LoadBitmap(TResId id) const;

HCURSOR LoadCursor(TResId id) const

HICON LoadIcon(const char far* name) const;

HMENU LoadMenu(TResId id) const;

HGLOBAL LoadResource(HRSRC hRsrc) const;

int LoadString(uint id, char far* buff, int maxChars) const;

string LoadString(uint id) const;

bool LowMemory();

TWindow* MakeWindow(TWindow* win);

operator HINSTANCE() const;

bool operator ==(const TModule& other) const;

void RestoreMemory();

void SetInstance(HINSTANCE hInstance);

void SetName(const char far* name);

RSRCHDLRPROC SetResourceHandler(const char far* type, RSRCHDLRPROC loadProc) const;

uint32 SizeofResource(HRSRC hRsrc) const;

TWindow* ValidWindow(TWindow* win);

Protected Data Members

HINSTANCE HInstance;

char far* Name;


TModule::lpCmdLine

See Also	TModule

Syntax

char far* lpCmdLine;

Description

A null-terminated string, lpCmdLine points to a copy of the command-line arguments passed when the module is loaded. Notice that lpCmdLine is different from the WIN32 lpCmdLine in which the full path name of the module is appended to the command-line arguments. Whether running under WIN16 or WIN32, ObjectWindows TModule::lpCmdLine data member includes only the command-line arguments. Note that the run-time library global variables _argv*[] and _argc contain identical information for both WIN16 and WIN32 APIs, and that _argv[0] points to the full path name of the module.


See Also

TApplication


TModule::Module

TModule

Syntax

extern TModule *Module;

Description

Holds a global pointer to the current module.


TModule::Status

See Also	TModule

Syntax

TStatus Status;

Description

Status contains the module status and is included for backward compatibility with ObjectWindows 1.0 applications. ObjectWindows 2.0 instead uses exceptions to handle errors. Setting Status to any nonzero value will throw a TXCompatibility exception.


See Also

TXCompatibility::MapStatusCodeToString


TModule Public Constructors and Destructor

TModule

Form 1

TModule(const char far* name, HINSTANCE hInstance, const char far* cmdLine);

Form 2

TModule(const char far* name, HINSTANCE hInstance);

Form 3

TModule(const char far* name, bool shouldLoad = true);

Destructor

virtual ~TModule();

Description

Form 1: Constructs a TModule object for an ObjectWindows DLL or program from within LibMain or WinMain. Calls InitModule to initialize hInstance and cmdLine.

Form 2: Constructs a TModule object that is an alias for an already loaded DLL or program with an available HInstance. When the TModule is destructed, the instance isn't automatically freed. name, which is optional, can be 0.

Form 3: Constructs a TModule object that is used as an alias for a DLL. If shouldLoad is true, TModule will automatically load and free the DLL. If shouldLoad is false, then the HInstance needs to be set later using InitModule.

Destructor

Destroys a TModule object and deletes lpCmdLine.


TModule::AccessResource

See Also	TModule

Syntax

int AccessResource(HRSRC hRsrc) const;

Description

Used for 16-bit applications, AccessResource finds the specified resource. The preferred method is to use FindResource.


See Also

TModule::FindResource


TModule::AllocResource

See Also	TModule

Syntax

HGLOBAL AllocResource(HRSRC hRsrc, uint32 size) const;

Description

Used for 16-bit applications, AllocResource loads a resource into memory. The preferred method is to use LoadResource.


See Also

TModule::LoadResource


TModule::CopyCursor

See Also	TModule

Syntax

HCURSOR CopyCursor(HCURSOR hCursor) const;

Description

Used for 16-bit applications, CopyCursor copies the cursor specified in hCursor. The return value is a handle to the duplicate cursor.


See Also

TIcon


TModule::CopyIcon

TModule

Syntax

HICON CopyIcon(HICON hIcon) const;

Description

Copies the icon specified in hIcon. The return value is a handle to the icon or 0 if unsuccessful. When no longer required, the duplicate icon should be destroyed.


TModule::Error

TModule

Form 1

virtual void Error(int errorCode);

Form 2

virtual int Error(xmsg& x, unsigned captionResId, unsigned promptResId=0);

Description

Form 1: Processes errors identified by the error value supplied in errorCode. Error displays the error code in a message box and asks the user if it is OK to continue. If the user does continue, the program might or might not be able to recover. If the user does not continue, the program terminates. Error can be overridden with another kind of exception handler. This function is included only for backward compatibility with ObjectWindows 1.0. If you are writing ObjectWindows 2.0 applications, use the following Error function instead.

Form 2: Called when fatal exceptions occur, Error takes an xmsg exception object, a resource ID for a message box caption, and an optional resource ID for a user prompt. By default, Error calls HandleGlobalException with the xmsg object and the strings obtained from the resources. An application (derived from TApplication which is derived from TModule) can reimplement this function to provide alternative behavior.

A nonzero status code is returned to indicate that an error condition is to be propagated; a zero status indicates that the condition has been handled and that it is OK to proceed. ObjectWindows uses this status code inside its message loop to allow the program to resume. The global error handler (defined in except.h), which displays the message text, is

int _OWLFUNC HandleGlobalException(xmsg& x, char* caption, char* canResume);


TModule::ExecDialog

TModule

Syntax

int ExecDialog(TDialog* dialog);

Description

Executes a dialog box. This function is included only for backward compatibility. Use TDialog::Execute instead.


TModule::FindResource

See Also	TModule

Syntax

HRSRC FindResource(TResId id, const char far* type) const;

Description

Finds the resource indicated by id and type and, if successful, returns a handle to the specified resource. If the resource cannot be found, the return value is zero. The id and type parameters either point to zero-terminated strings or specify an integer value. type can be one of the standard resource types defined below.

Value of type	Resource

RT_ACCELERATOR	Accelerator table

RT_BITMAP	Bitmap

RT_CURSOR	Cursor

RT_DIALOG 	Dialog box

RT_FONT	Font

RT_FONTDIR	Font directory

RT_ICON	Icon

RT_MENU	Menu

RT_RCDATA	User-defined resource

RT_STRING	String


See Also

TResID


TModule::GetClientHandle

TModule

Syntax

HWND GetClientHandle(HWND hWnd);

Description

Gets the handle to the client window. This function is included only for backward compatibility with ObjectWindows 1.0.


TModule::GetClassInfo

See Also	TModule

Syntax

bool GetClassInfo(const char far* name, WNDCLASS far* wndclass) const;

Description

Used particularly for subclassing, GetClassInfo gets information about the window class specified in wndclass. name points to a 0-terminated string that contains the name of the class. wndclass points to the WNDCLASS structure that receives information about the class. If successful, GetClassInfo returns nonzero. If a matching class cannot be found, GetClassInfo returns zero.


See Also

WNDCLASS struct


TModule::GetInstance

TModule

Syntax

HINSTANCE GetInstance() const;

Description

Returns the instance handle for this module.


TModule::GetInstanceData

TModule

Syntax

int GetInstanceData(void* data, int len) const;

Description

Used only for 16-bit applications, GetInstanceData gets data from an already running instance of an application. len is the size of the buffer.


TModule::GetModuleFileName

TModule

Syntax

int GetModuleFileName(char far* buff, int maxChars);

Description

Returns the expanded file name (path and file name) of the file from which this module was loaded. buff points to a buffer that holds the path and file name. maxChars specifies the length of the buffer. The expanded filename is truncated if it exceeds this limit. GetModeFileName returns 0 if an error occurs.


TModule::GetModuleUsage

TModule

Syntax

int GetModuleUsage() const;

Description

Used only for 16-bit applications, GetModuleUsage returns the reference count of the module, if successful. The reference count is incremented by one each time a module is loaded, and decremented by one each time a module is freed.


TModule::GetName

See Also	TModule

Syntax

const char far* GetName() const;

Description

Gets the name of the module.


See Also

::GetName (Windows API)


TModule::GetParentObject

See Also	TModule

Syntax

TWindow* GetParentObject(HWND hWndParent);

Description

Gets a handle to the parent window. This function is included only for backward compatibility with ObjectWindows 1.0.


See Also

::GetParentObject (Windows API)


TModule::GetProcAddress

TModule

Syntax

FARPROC GetProcAddress(const char far* fcnName) const;

Description

Returns the entry-point address of the exported function fcnName if the function is found. Returns NULL otherwise.


TModule::InitModule

TModule

Syntax

void InitModule(HINSTANCE hInstance, const char far* cmdLine);

Description

Performs any instance initialization necessary for the module. If the module cannot be created, a TXInvalidModule exception is thrown.


TModule::IsLoaded

TModule

Syntax

bool IsLoaded() const;

Description

Returns a nonzero value if the instance handle is loaded. Use this function primarily to ensure that a given instance is loaded.


TModule::LoadAccelerators

TModule

Syntax

HACCEL LoadAccelerators(TResId id) const;

Description

Loads the accelerator table resource specified by id. LoadAccelerators loads the table only if it has not been previously loaded. If the table has already been loaded, LoadAccelerators returns a handle to the loaded table.


TModule::LoadBitmap

See Also	TModule

Syntax

HBITMAP LoadBitmap(TResId id) const;

Description

Loads the bitmap resource specified by id. If the bitmap cannot be found, LoadBitmap returns 0.


See Also

TBitMap

TResID

::LoadBitmap (Windows API)

OBM_XXXX values (Windows API)


TModule::LoadCursor

See Also	TModule

Syntax

HCURSOR LoadCursor(TResId id) const

Description

Loads the cursor resource specified by id into memory and returns a handle to the cursor resource. If the cursor resource cannot be found or identifies a resource that is not a cursor, LoadCursor returns 0.


See Also

TCursor

TResID

::LoadCursor (Windows API)


TModule::LoadIcon

See Also	TModule

Syntax

HICON LoadIcon(const char far* name) const;

Description

Loads the icon resource indicated by the parameter, name, into memory. LoadIcon loads the icon only if it has not been previously loaded. If the icon resource cannot be found, LoadIcon returns 0.

LoadIcon can be used to load a predefined Windows icon if name points to one of the Windows IDI_XXXX values.


See Also

TIcon

::LoadIcon (Windows API)

IDI_XXXX values (Windows API)


TModule::LoadMenu

See Also	TModule

Syntax

HMENU LoadMenu(TResId id) const;

Description

Loads the menu resource indicated by id into memory. If the menu resource cannot be found, LoadMenu returns 0.


See Also

TMenu

::LoadMenu (Windows API)


TModule::LoadResource

TModule

Syntax

HGLOBAL LoadResource(HRSRC hRsrc) const;

Description

Loads a resource indicated by hRsrc into memory and returns a handle to the memory block that contains the resource. If the resource cannot be found, the return value is 0. The hRsrc parameter must be a handle created by FindResource.

LoadResource loads the resource into memory only if it has not been previously loaded. If the resource has already been loaded, LoadResource increments the reference count by one and returns a handle to the existing resource. The resource remains loaded until it is discarded.


TModule::LoadString

TModule

Form 1

int LoadString(uint id, char far* buff, int maxChars) const;

Form 2

string LoadString(uint id) const;

Description

Form 1: Loads a string resource identified by id into the buffer pointed to by buff. maxChars indicates the size of the buffer to which the zero-terminated string is copied. A string longer than the length specified in maxChars is truncated. The return value is the number of characters copied into the buffer, or 0 if the string resource does not exist.

Form 2: Loads a string resource identified by id


TModule::LowMemory

TModule

Syntax

bool LowMemory();

Description

This function, which is obsolete, always returns 0.


TModule::MakeWindow

TModule

Syntax

TWindow* MakeWindow(TWindow* win);

Description

This function is obsolete. Use the TWindow::Create function instead.


TModule::operator ==

TModule

Syntax

bool operator ==(const TModule& other) const;

Description

Returns true if this instance is equal to the other instance; otherwise, returns false.


TModule::operator HINSTANCE

TModule

Syntax

operator HINSTANCE() const;

Description

Returns the handle of the application or DLL module represented by this TModule. The handle must be supplied as a parameter to Windows when loading resources.


TModule::RestoreMemory

TModule

Syntax

void RestoreMemory();

Description

This function, which is obsolete, restores memory.


TModule::SetInstance

TModule

Syntax

void SetInstance(HINSTANCE hInstance);

Description

Sets the instance handle for this TModule. SetInstance is used for special cases in which the hInstance is not known when the module is constructed.


TModule::SetName

TModule

Syntax

void SetName(const char far* name);

Description

Accessor function that sets the name of the module.


TModule::SetResourceHandler

TModule

Syntax

const RSRCHDLRPROC SetResourceHandler(const char far* type, RSRCHDLRPROC loadProc) const;

Description

Used for 16-bit applications, SetResourceHandler installs a callback function that loads resources. type points to a resource type. loadProc is the address of the callback procedure. If successful, SetResourceHandler returns a pointer to a previously installed resource handler. If no resource handler has been installed, SetResourceHandler returns a pointer to the default handler. This function is useful for handling user-defined resource types.


TModule::SizeOfResource

TModule

Syntax

uint32 SizeofResource(HRSRC hRsrc) const;

Description

Returns the size, in bytes, of the resource indicated by hRscr. The resource must be a resource handle created by FindResource. If the resource cannot be found, the return value is 0.

Because of alignment in the executable file, the returned size might be larger than the actual size of the resource. An application cannot rely on SizeofResource for the exact size of a resource.


TModule::ValidWindow

TModule

Syntax

TWindow* ValidWindow(TWindow* win);

Description

This function, which is obsolete, returns a handle to the valid window.


TModule::HInstance

TModule

Syntax

HINSTANCE HInstance;

Description

Contains the executing instance of either the application or DLL module. The instance must be supplied as a parameter to Windows when loading resources.


TModule::Name

TModule

Syntax

char far* Name;

Description

Holds the name of the application or DLL module.


TModule::TXInvalidModule Class

TModule	OWL Hierarchy	Inheritance

Header File

module.h

Description

A nested class, TXInvalidModule describes an exception that results from an invalid module. A window throws this exception if it can't create a valid TModule object.

Public Constructor

TXInvalidModule();

Public Member Functions

TXOwl* Clone();

void Throw();


TModule Public Constructor
TModule::TXInvalidModule Public Constructor

TModule::TXInvalidModule

Syntax

TXInvalidModule();

Description

Constructs a TXInvalidModule object.


TModule::Clone

TModule::TXInvalidModule

Syntax

TXOwl* Clone();

Description

Makes a copy of the TXInvalidModule exception object.


TModule::Throw

TModule::TXInvalidModule

Syntax

void Throw();

Description

Throws the TXInvalidModule exception object.


TOleClientDC Class

See Also	OWL Hierarchy	Inheritance

Header file

olewindo.h

Description

Derived from TClientDC, TOleClientDC is a helper class that translates between two different coordinate systems. For example, the window's logical points may be measured in HIMETRIC or twips, whereas the coordinates of the actual output device (the viewport) may be measured in pixels. Without the help of this class, you would need to create a client DC and then setup the window's logical coordinates (its origin) and its width and height (its extent) as well as the viewport's origin (measured in device coordinates) and extent. Instead, TOleClientDC performs these calculations for you by mapping logical points to device points and vice versa.

TOleClientDC works with a TOleWindow object. By default, TOleClientDC takes care of both scaling (adjusting the extents of the window and the viewport) and scrolling (adjusting the origins of the window and the viewport).

Public Constructor

TOleClientDC(TOleWindow& win, bool scale = true);


See Also

TClientDC

TOleWindow


TOleClientDC Public Constructor

TOleClientDC

Constructor

TOleClientDC(TOleWindow& win, bool scale = true);

Description

Constructs a TOleClientDC object . The parameter win references the window that TOleClientDC uses to create a device context (DC). If the scale parameter is true, TOleClientDC takes care of scaling. However, if your application handles scaling, you can pass scale as false.

Scrolling is controlled by the presence of a scroller (TScroller). TOleClientDC by default takes care of both scaling and scrolling.


TOleDocument Class

See Also	OWL Hierarchy	Inheritance

Header File

oledoc.h

Description

Derived from TStorageDocument, TOleDocument implements the document half of the Doc/View pair. It manages the document's data while the corresponding TOleView object determines how the data is displayed on the screen. Basically, TOleDocument is a TStorageDocument with a knowledge of TOcDocument through its pointer to TOcDocument.

TOleDocument is responsible for creating compound documents, closing documents, reading documents from storage, and writing documents to storage. In the case of a server, the document consists of a single object. In the case of a container, the document can consist of one or more embedded objects (also referred to as parts).

To accomplish these tasks, TOleDocument talks to the underlying ObjectComponents classes through the use of functions such as GetOcApp, GetOcDoc, and SetOcDoc.

Public Constructors and Destructors

TOleDocument(TDocument* parent = 0);

~TOleDocument();

Public Member Functions

virtual bool CanClose();

bool Close();

bool Commit(bool force);

virtual IStorage* GetNewStorage();

TOcApp* GetOcApp();

TOcDocument* GetOcDoc();

virtual bool InitDoc();

bool Open(int mode, const char far* path);

bool PathChanged();

virtual void PreOpen();

virtual bool Read();

virtual bool ReleaseDoc();

bool Revert(bool clear);

void SetOcDoc(TOcDocument* doc);

virtual bool SetStorage(IStorage* stg);

virtual bool Write();


See Also

TOcRemView


compound documents

Documents that can hold a variety of embedded objects from various source applications


storage

An area within a file where data is stored


TOleDocument Public Constructor and Destructor

TOleDocument

Constructor

TOleDocument(TDocument* parent = 0);

Description

Constructs a TOleDocument object associated with the given parent TDocument object.

Destructor

~TOleDocument();

Description

Destroys the TOleDocument object.  In the case of an OLE container, the compound file remains open until all the views shut down.


TOleDocument::SetOcDoc

See Also	TOleDocument

Syntax

void SetOcDoc(TOcDocument* doc);

Description

Sets the ObjectComponents document associated with this TOleDocument object.


See Also

TOleDocument::GetOcDoc


TOleDocument::GetOcDoc

See Also	TOleDocument

Syntax

TOcDocument* GetOcDoc();

Description

Returns the ObjectComponents document associated with this TOleDocument object.


See Also

TOleDocument::SetOcDoc


TOleDocument::GetOcApp

See Also	TOleDocument

Syntax

TOcApp* GetOcApp();

Description

Returns the ObjectComponents application associated with this TOleDocument object.


See Also

TOcApp


TOleDocument::PreOpen

See Also	TOleDocument

Syntax

virtual void PreOpen();

Description

Before the document is actually opened, PreOpen gives the derived class a chance to perform a particular operation; for example, setting a different open mode for the compound document.


See Also

dtxxxx document constants

ofxxxx document open enum


TOleDocument::Write

See Also	TOleDocument

Syntax

virtual bool Write();

Description

Saves the embedded objects to the compound file. A container should call this function to save its embedded objects to storage.


See Also

TOleDocument::Read


TOleDocument::Read

See Also	TOleDocument

Syntax

virtual bool Read();

Description

Loads the embedded objects from the compound file. A container should call this function to load any embedded objects.


See Also

TOleDocument::Write


TOleDocument::SetStorage

TOleDocument

Syntax

virtual bool SetStorage(IStorage* stg);

Description

Attaches the IStorage pointer (stg) to this document. If successful, SetStorage returns true.


IStorage

An OLE storage interface that ObjectComponents implements when it needs to assign storage to a document


TOleDocument::CanClose

TOleDocument

Syntax

virtual bool CanClose();

Description

Prepares the document for closing. Before closing the current document, checks to see if all child documents can be closed. If any child returns false, CanClose returns false and aborts the process. If all children return true, CanClose checks to see if the document has been changed. If so, it asks the user to save the document, discard any changes, or cancel the operation. If the document has not been changed and all child documents return true, this CanClose function returns true, thus indicating that the document can be closed.

CanClose also calls ReleaseDoc on its associated ObjectComponents document to make sure that all the embedded objects are closed properly.


TOleDocument::Close

TOleDocument

Syntax

bool Close();

Description

Ensures that the IStorage is released properly and disconnects any active server in the document. A compound file must be closed before it is reopened.


TOleDocument::ReleaseDoc

See Also	TOleDocument

Syntax

virtual bool ReleaseDoc();

Description

Releases the ObjectComponents document when the server is finished using the document.


See Also

TOleDocument::CanClose


TOleDocument::Revert

TOleDocument

Syntax

bool Revert(bool clear);

Description

Performs the reverse of Commit. Revert cancels any changes made to the document since the last time the document was saved to storage.


TOleDocument::InitDoc

TOleDocument

Syntax

virtual bool InitDoc();

Description

Overrides the TDocument::InitDoc function and creates or opens a compound file so that there is an IStorage associated with this document's embedded objects. Uses a TOcDocument object to perform the actual interaction with the OLE IStorage  and IStream interfaces, which are ultimately responsible for establishing the relationship between a compound file and its storage.


TOleDocument::GetNewStorage

TOleDocument

Syntax

virtual IStorage* GetNewStorage();

Description

Typically used in a SaveAs menu selection, GetNewStorage gets a new storage for the document.

For example, If the document's path changes, use this function to create a new storage.


TOleDocument::PathChanged

TOleDocument

Syntax

bool PathChanged();

Description

Checks to see if the current document's path is the same as the TOcDocument's path. If the paths are not the same, PathChanged returns true.


TOleDocument::Commit

TOleDocument

Syntax

bool Commit(bool force);

Description

Commits the current document's data to storage. If force is true and the data is not dirty, all data is written to storage and Commit returns true. If force is false, the data is written only if it is dirty.


dirty

The data has been changed since the last save operation.


TOleDocument::Open

See Also	TOleDocument

Syntax

bool Open(int mode, const char far* path);

Description

Loads the embedded objects, if any, using the path specified in path. mode is a combination of bits that specify how the embedded objects are opened (for example, read only, read/write, and so on). By default, objects are opened in ofReadWrite and ofTransacted modes.


See Also

ofxxxx document open enum


TOleFactoryBase<> Class

See Also	Inheritance

Header File

olefacto.h

Description

A template class, TOleFactoryBase<> creates callback code for ObjectWindows classes. The main purpose of the factory code is to provide a callback function, Create, that ObjectComponents calls to create objects.

Just as a recipe consists of a list of instructions about how to make a particular kind of food, a template, such as TOleFactoryBase<>, contains instructions about how to make an object, in this case, a factory object. TOleFactoryBase<> includes two public member functions. The three additional functions are passed as template arguments. Although these template arguments actually belong to the class that is instantiated when you fill in the arguments to TOleFactoryBase<>, they are described here for convenience.

Use TOleFactoryBase<> to manufacture objects in general, whether or not they are embedded, OLE-enabled, or use the Doc/View model. These objects might or might not be connected to OLE.

The callouts are supplied through the arguments passed to the template class. The factory base class takes three template parameters: the application type, a set of functions to create the object, and a set of functions to create an automation object. Depending on the arguments passed, you can make the following OLE-enabled components:

Doc/View components that are automated

Doc/View components that are not automated

Non-Doc/View components that are automated

Non-Doc/View components that are not automated

ObjectWindows provides a standard implementation for object creation and automation. Factory Template Classes gives an overview of these classes.

By using TOleFactoryBase<> to obtain an OLE interface for your application, you can make objects that are accessible to OLE. That is, TOleFactoryBase<> handles any relationships with IUnknown, a standard OLE interface.

Public Member Functions

operator TComponentFactory();

static IUnknown* Create(IUnknown* outer, uint32 options, uint32 id);

Template Arguments

static T* CreateApp(options);

static IUnknown* CreateObject(TApplication* app, TDocTemplate* tpl, IUnknown* outer);

static void DestroyApp(T* app);


See Also

TComponentFactory typedef

TOcRegistrar class

TAutoFactory class


TOleFactoryBase::TComponentFactory

TOleFactoryBase

Syntax

operator TComponentFactory();

Description

Converts the object into a pointer to the factory. ObjectComponents uses this pointer to create the object.


TOleFactoryBase::CreateApp

See Also	TOleFactoryBase

Syntax

static T* CreateApp(options);

Description

Creates a new application. By default, it creates a new application of template type T with no arguments. This is a static function that you can override in your application.

The options are those passed to the factory. They can be one of the TOcAppMode enum values (for example, amRun, amEmbedding, and so on) that indicate the application's mode when running and indicate the options to the factory.


See Also

TOleFactoryBase::DestroyApp


TOleFactoryBase::CreateObject

See Also	TOleFactoryBase

Syntax

static IUnknown* CreateObject(TApplication* app, TDocTemplate* tpl, IUnknown* outer);

Description

Creates an object using the document template referred to in tpl and the application specified in app. The outer parameter refers to the controlling IUnknown interface of the object with which this object is going to be aggregated. If outer is 0, the object is an independent object.

You can override this static function to create your own object at run-time.


See Also

TOleFactoryBase::DestroyApp

TOcView class


TOleFactoryBase::DestroyApp

See Also	TOleFactoryBase

Syntax

static void DestroyApp(T* app);

Description

Destroys the application (app) by unregistering the object and deleting it.


See Also

TOleFactoryBase::CreateApp


TOleFactoryBase::Create

See Also	TOleFactoryBase

Syntax

static IUnknown* Create(IUnknown* outer, uint32 options, uint32 id);

Description

A TComponentFactory callback function that creates or destroys the application or creates objects. If an application object does not already exist, Create creates a new one. The outer argument points to the OLE 2 IUnknown  interface with which this object aggregates itself. If outer is 0,  If outer is 0, the object will become an independent object.

The options argument indicates the application's mode while it is running. The values for options are either set from the command line or set by ObjectComponents. They are passed in by the Registrar to this callback. The application looks at these flags in order to know how to operate, and the factory callback looks at them in order to know what to do. For example, a value of amExeMode indicates that the server is running as an .EXE either because it was built as an .EXE or because it is a .DLL that was launched by an .EXE stub and is now running as an executable program. The TOcAppMode enum description shows the possible values for the options argument.

If the application already exists and the object ID (id) equals 0, Create returns the application's OLE interface. Otherwise, it calls OCInit to create a new TOcApp and register the options from TOcAppMode enum, which contains OLE-related flags used in the application's command line. (These flags tell the application whether it has been run as a server, whether it needs to register itself, and so on.) If a component ID was passed, that becomes the component; otherwise, Create runs the application itself based on the values of the TOcAppMode enum and returns the OLE interface.


See Also

TOleFactoryBase::DestroyApp

TOcAppMode enum


TOleFrame Class

OWL Hierarchy	Inheritance

Header File

oleframe.h

Description

Derived from TDecoratedFrame, TOleFrame provides user-interface support for the main window of a Single Document Interface (SDI) OLE application. Because it inherits TDecoratedFrame's functionality, TOleFrame is able to position decorations, such as toolbars, around the client window. Because of its OLE frame functionality, you will always want to create a TOleFrame as a main frame.  For example, TOleFrame supports basic container operations, such as

Creating space in a container's frame window that the server has requested

Merging the container's menu and the server's menu

Processing accelerators and other messages from the server's message queue

In addition to supporting the customary frame window operations and event-handling, TOleFrame provides functionality that supports OLE 2 menu merging for pop-up menus.

Through the use of the  EvOcXxxx event-handling member functions, TOleFrame responds to ObjectComponents messages sent to both the server and the container applications. Although most of the messages and functions provide container support, one message, EvOcAppShutDown, is server related, and one function, GetRemViewBucket, supplies server support. Whether TOleFrame functions as a container or a server, it always has a pointer to a corresponding TOcApp.

Public Constructors and Destructor

TOleFrame(const char far* title, TWindow* clientWnd, bool trackMenuSelection = false,  TModule* module = 0);

~TOleFrame();

Public Member Functions

void AddUserFormatName(char far* name, char far* resultName, char far* id);

TOcApp* GetOcApp();

TWindow* GetRemViewBucket();

void SetOcApp(TOcApp* app);

Protected Member Functions

bool CanClose();

void CleanupWindow();

void Destroy(int retVal);

void DestroyStashedPopups();

void EvActivateApp(bool active, HTASK hTask);

bool EvOcAppBorderSpaceReq(TRect far*);

bool EvOcAppBorderSpaceSet(TRect far*);

void EvOcAppDialogHelp(TOcDialogHelp far& dh);

bool EvOcAppFrameRect(TRect far* rect);

bool EvOcAppInsMenus(TOcMenuDescr far& sharedMenu);

bool EvOcAppMenus(TOcMenuDescr far& md);

bool EvOcAppProcessMsg(MSG far* msg);

void EvOcAppRestoreUI();

bool EvOcAppShutdown();

void EvOcAppStatusText(const char far*);

LRESULT EvOcEvent(WPARAM wParam, LPARAM lParam);

void EvSize(uint sizeType, TSize& size);

void EvTimer(uint timerId);

void SetupWindow();

void StashContainerPopups(const TMenuDescr& shMenuDescr);

Protected Data Members

HMENU HoldMenu;

TOcApp* OcApp;

int StashCount;

TMenu StashedContainerPopups;

Response Table Entries

EV_ macros and member functions


TOleFrame Public Constructors and Destructor

TOleFrame

Constructor Syntax

TOleFrame(const char far* title, TWindow* clientWnd, bool trackMenuSelection = false, TModule*  module = 0);

Description

Constructs a TOleFrame object with the specified caption for the frame window (title), the client window (clientWnd), and module instance. The trackMenuSelection parameter indicates whether or not the frame window should track menu selections (that is, display hint text in the status bar of the window when a menu item is highlighted).

Destructor Syntax

~TOleFrame();

Description

Destroys a TOleFrame object.


TOleFrame::GetOcApp

See Also	TOleFrame

Syntax

TOcApp* GetOcApp();

Description

Gets the ObjectComponents application associated with this frame window.


See Also

TOcApp

TOleFrame::SetOcApp


TOleFrame::SetOcApp

See Also	TOleFrame

Syntax

void SetOcApp(TOcApp* app);

Description

Sets the ObjectComponents application associated with this frame window to the applications specified in the app parameter.


See Also

TOcApp

TOleFrame::GetOcApp


TOleFrame::AddUserFormatName

See Also	TOleFrame

Syntax

void AddUserFormatName(char far* name, char far* resultName, char far* id);

Description

Adds user defined formats and the corresponding names to the list of clipboard formats. Use this function if you want to associate a clipboard data format (name) with the description of the data format as it appears to users in the Help text of the Paste Special dialog box (resultName). To use a standard clipboard format, set the id parameter to an appropriate constant (for example, CF_TEXT). Otherwise, if the format is identified by a string, pass the string as the name and omit the ID.


See Also

TOcApp::AddUserFormatName


TOleFrame::GetRemViewBucket

TOleFrame

Syntax

TWindow* GetRemViewBucket();

Description

Returns a pointer to the OLE frame's hidden helper window that holds all inactive server windows. It can also hold in-place tool bars and TOleView windows.


TOleFrame::SetupWindow

See Also	TOleFrame

Syntax

void SetupWindow();

Description

 Associates the ObjectComponents application with the window's HWND so that the TOcApp and the window can communicate. Prepares a place to insert the server's toolbars when in-place editing of the embedded object occurs.


See Also

TOcApp


TOleFrame::CanClose

See Also	TOleFrame

Syntax

bool CanClose();

Description

Returns true if the frame window can be closed. Tests to see if both the TOcApp  and all child windows can close. If the application and all child windows return true, CanClose closes the frame window.


See Also

TOcApp


TOleFrame::CleanupWindow

See Also	TOleFrame

Syntax

void CleanupWindow();

Description

Performs normal window cleanup of any HWND-related resources. For .DLL servers, CleanupWindow destroys the idle timer.


See Also

TWindow::CleanupWindow

TOleFrame::EvTimer


TOleFrame::Destroy

TOleFrame

Syntax

void Destroy(int retVal);

Description

Checks with all the connected servers to ensure that they can close before destroying the frame window. If the user closes the application with objects still embedded, Destroy hides the frame window instead of destroying it.


TOleFrame::EvTimer

See Also	TOleFrame

Syntax

void EvTimer(uint timerId);

Description

If this is a .DLL server, EvTimer responds to a timer message by running an idle loop if the message queue is empty.


See Also

TOleFrame::CleanupWindow


TOleFrame::EvSize

See Also	TOleFrame

Syntax

void EvSize(uint sizeType, TSize& size);

Description

Responds to an EV_WM_SIZE message indicating a change in the frame window's size and forwards this information to the TOcApp, which then notifies any in-place server. The server uses this information to change the size of its toolbar, if necessary.


See Also

TOcApp::EvActivate


TOleFrame::EvActivateApp

See Also	TOleFrame

Syntax

void EvActivateApp(bool active, HTASK hTask);

Description

Responds to a WM_ACTIVATEAPP message sent when a window is activated or deactivated. If active is true, the window is being activated.

This message is sent to the top-level window being deactivated before it is sent to the top-level window being activated. hTask is a handle to the current process.

This event is forwarded to the TOcApp object, which activates an in-place server if one exists.


See Also

TOcApp


TOleFrame::EvOcEvent

TOleFrame

Syntax

LRESULT EvOcEvent(WPARAM wParam, LPARAM lParam);

Description

Responds to a WM_OCEVENT message and subdispatches it to one of the EvOcXxxx event-handling functions based on the value of wParam. WM_OCEVENT messages are sent by ObjectComponents when it needs to communicate with an OLE-generated event; for example, if a server wants to display toolbars.


TOleFrame::EvOcAppInsMenus

TOleFrame

Syntax

bool EvOcAppInsMenus(TOcMenuDescr far& sharedMenu);

Description

Responds to an OC_APPINSMENUS message by merging the container's menu into the shared menu. The sharedMenu parameter refers to this merged menu.


TOleFrame::EvOcAppMenus

TOleFrame

Syntax

bool EvOcAppMenus(TOcMenuDescr far& md);

Description

Responds to an OC_OCAPPMENUS sent to the container. The response is to install a merged menu bar.


TOleFrame::EvOcAppProcessMsg

TOleFrame

Syntax

bool EvOcAppProcessMsg(MSG far* msg);

Description

Responds to an OC_APPROCESSMSG message sent to the container asking the server to process accelerators and other messages from the container's message queue.


TOleFrame::EvOcAppFrameRect

TOleFrame

Syntax

bool EvOcAppFrameRect(TRect far* rect);

Description

Responds to an OC_APPFRAMERECT message sent to a container. The response is to get the coordinates of the client area rectangle of the application's main window.


TOleFrame::EvOcAppBorderSpaceReq

See Also	TOleFrame

Syntax

bool EvOcAppBorderSpaceReq(TRect far* rect);

Description

Responds to an OC_APPBORDERSPACEREQ message sent to a container. The response is to ask the container if it can give border space in its frame window to the server.


See Also

TOcApp::BorderSpaceSet


TOleFrame::EvOcAppBorderSpaceSet

See Also	TOleFrame

Syntax

bool EvOcAppBorderSpaceSet(TRect far* rect);

Description

Responds to an OC_APPBORDERSPACESET message by making room in the container's frame window for the border space that the server has requested.


See Also

TOcApp::BorderSpaceReq


TOleFrame::EvOcAppStatusText

TOleFrame

Syntax

void EvOcAppStatusText(const char far*);

Description

Responds to an OC_APPSTATUSTEXT message by displaying text from the server on this container's status bar.


TOleFrame::EvOcAppRestoreUI

TOleFrame

Syntax

void EvOcAppRestoreUI();

Description

Responds to an OC_APPRESTOREUI message by restoring the container's normal menu and borders because in-place editing has finished.


TOleFrame::EvOcAppDialogHelp

See Also	TOleFrame

Syntax

void EvOcAppDialogHelp(TOcDialogHelp far& dh);

Description

Responds to an OC_APPDIALOGHELP message. The dh parameter refers to one of the TOcDialogHelp enum constants that indicate the kind of dialog box the user has open. For example, dhBrowseLinks indicates that the Links dialog box is open. The TOcDialogHelp enum lists the help constants and their dialog box equivalents.


See Also

TOcDialogHelp enum


TOleFrame::EvOcAppShutdown

TOleFrame

Syntax

bool EvOcAppShutdown();

Description

Responds to an OC_APPSHUTDOWN message indicating that the last embedded object has been closed. The response is to shut down the server.


TOleFrame::OcApp

See Also	TOleFrame

Syntax

TOcApp* OcApp;

Description

Points to the ObjectComponents application associated with this frame window.


See Also

TOcApp


TOleFrame::StashContainerPopups

See Also	TOleFrame

Syntax

void StashContainerPopups(const TMenuDescr& shMenuDescr);

Description

Stores a local copy of the pop-up menus so they can be used for menu merging and then destroyed later by DestroyStashedPopups. shMenuDescr is the shared menu descriptor to be stored. Increments StashCount each time the pop-up menus are saved.


See Also

TOleFrame::DestroyStashedPopups

TMenuDescr


TOleFrame::DestroyStashedPopups

See Also	TOleFrame

Syntax

void DestroyStashedPopups();

Description

Destroys the previously stored shared pop-up menus. Checks to see if StashCount is 0 before destroying the menus.


See Also

TOleFrame::StashContainerPopups

TOleFrame::StashCount


TOleFrame:StashedContainerPopups
TOleFrame::StashedContainerPopups

See Also	TOleFrame

Syntax

TMenu StashedContainerPopups;

Description

Holds the stored, shared popup menus.


See Also

StashContainerPopups

TOleFrame::StashCount


TOleFrame::StashCount

See Also	TOleFrame

Syntax

int StashCount;

Description

Holds the number of menu bars that have been stored. This number indicates how many active in-place editing sessions you have open.


See Also

StashContainerPopups

TOleFrame::DestroyStashedPopups


TOleFrame::HoldMenu

TOleFrame

Syntax

HMENU HoldMenu;

Description

Holds the handle to the container's previously saved copy of the menu.


TOleFrame Response Table Entries

TOleFrame

Response table entry	Member function

EV_WM_SIZE	EvSize

EV_WM_ACTIVATEAPP	EvActivateApp

EV_MESSAGE(WM_OCEVENT, EvOcEvent)	EvOcEvent

EV_OC_APPINSMENUS	EvOcAppInsMenus

EV_OC_APPMENUS	EvOcAppMenus

EV_OC_APPROCESSMSG	EvOcAppProcessMsg

EV_OC_APPFRAMERECT	EvOcAppFrameRect

EV_OC_APPBORDERSPACEREQ	EvOcAppBorderspaceReq

EV_OC_APPBORDERSPACESET	EvOcAppBorderSpaceSet

EV_OC_APPSTATUSTEXT	EvOcAppStatusText

EV_OC_APPRESTOREUI	EvOcAppRestoreUI

EV_OC_APPSHUTDOWN	EvOcAppShutDown


TOleLinkView Class

See Also

Header File

oleview.h

Description

Derived from TView, TOleLinkView provides embedding and linking support for a portion of a document instead of an entire document. With the added functionality of TOleLinkView, a container gains the ability to embed or link to a selection within the server document.

The main purpose of a class derived from TOleLinkView is to attach a view to a portion of a document whenever a link is created to a selection within a server document. After this link is established, any changes made to the linked selection in the server document are sent to the container via the following sequence of steps:

1.	When a user changes the server document, TOleLinkView receives a notification message

2.	TOleLinkView checks to see if the selection it represents has changed. If the selection has changed, TOleLinkView notifies TOcLinkView about the change.

3.	When TOcLinkView receives the change message, it notifies the container that the selection has changed.

Non-Doc/View servers need to maintain a list of the TOleLinkViews attached to the document so that change notifications can be sent to each one of the views.

Public Member Functions

TString GetMoniker();

const char far* GetViewName();

static const char far* StaticName();

virtual bool UpdateLinks();

virtual bool VnLinkMoniker(TString moniker);

virtual bool VnLinkView(TOcLinkView& view);

Public Constructor and Destructor

TOleLinkView(TDocument& doc, TOcLinkView& view);

~TOleLinkView();

Protected Data Member

TOcLinkView& OcLinkView;

Response Table Entries

EV_ macros and member functions


See Also

TOleView

TOleWindow

TOcView

TOcRemView


TOleLinkView Public Constructor and Destructor

TOleLinkView

Constructor Syntax

TOleLinkView(TDocument& doc, TOcLinkView& view);

Description

Constructs a TOleLinkView object associated with the given document object (doc) and view (view).

Destructor Syntax

~TOleLinkView();

Description

Destroys the TOleLinkView object and detaches the view from the associated document.


TOleLinkView::GetMoniker

See Also	TOleLinkView

Syntax

TString GetMoniker();

Description

Returns the moniker  for the selection in a server document associated with this TOleLinkView container's view. By looking at the moniker, the application can find the corresponding objects in its document.


See Also

TOcLinkView:GetMoniker


Moniker

The source file's path name and the object hierarchy for a linked object.

A moniker functions much like a map by showing where the linked object's data is stored and explaining how to find the data. For example, the moniker returned from a word processor for a selected range of text could be the start and end offset of a text stream. The moniker returned for a spreadsheet range could be something like A1:D6. Anything that a server application can use to map to its data can be used as a moniker.


TOleLinkView::UpdateLinks

See Also	TOleLinkView

Syntax

virtual bool UpdateLinks();

Description

When any changes occur to the server document, UpdateLinks updates all containers linked to the view of the server document. If successful, it returns true.


See Also

TOcLinkView::Invalidate


TOleLinkView::VnLinkMoniker

See Also	TOleLinkView

Syntax

virtual bool VnLinkMoniker(TString moniker);

Description

Returns true if a TOleLinkView object is associated with the given server's TOcRemView. In contrast to VnLinkView, this function searches for the view using the specified server's moniker.

When the document receives a request for the TOleLinkView associated with a particular moniker, the document sends a vnLinkView notification message to all its attached views. The handler for vnLinkMoniker in TOleLinkView simply returns true if the handler finds a view associated with the moniker.


See Also

TOcLinkView::GetMoniker


TOleLinkView::VnLinkView

See Also	TOleLinkView

Syntax

virtual bool VnLinkView(TOcLinkView& view);

Description

Returns true if a TOleLinkView object is associated with the server's TOcRemView, the server's remote link view object. A TOcRemView is the object created by a linking and embedding server so that the server can draw its OLE object in a metafile used by the container. In contrast to VnLinkMoniker, this function searches for the TOleLinkView object using a reference to the view.


See Also

TOcLinkView


TOleLinkView::GetViewName

TOleLinkView

Syntax

const char far* GetViewName();

Description

Overrides TView's virtual GetViewName function and returns the static name, "Link View".


TOleLinkView::StaticName

See Also	TOleLinkView

Syntax

static const char far* StaticName();

Description

Returns the constant string "Link View" that is displayed in the user interface selection box.


See Also

TListView::StaticName


TOleLinkView::OcLinkView

TOleLinkView

Syntax

TOcLinkView& OcLinkView;

Description

The TOcLinkView connector object associated with this view.


TOleLinkView Response Table Entries

TOleLinkView

Response table entry	Member function

EV_VN_LINKVIEW	VnLinkView

EV_VN_LINKMONIKER	VnLinkMoniker


TOleMDIFrame Class

See Also	OWL Hierarchy

Header File

olemdifr.h

Description

Derived from TMDIFrame and TOleFrame, TOleMDIFrame provides OLE user-interface support for the main window of a Multiple Document Interface (MDI) application. TOleMDIFrame also talks directly to the ObjectComponents classes through the use of a pointer to the OcApp object.

TOleMDIFrame inherits functionality from TMDIFrame that supports the use of MDI frame windows designed to serve as the main windows of an MDI-compliant application. It also inherits decorated frame window functionality that supports the addition of decorations (such as toolbars and status lines) to the frame window. In addition, TOleMDIFrame inherits the ability to

Create space that the server has requested in a container's frame window

Merge the container's menu into the server's menu

Process accelerators and other messages from the server's message queue

Support OLE 2 menu merging for pop-up menus

TOleMDIFrame also inherits from TOleFrame the ability to talk directly to the ObjectComponents classes through the use of a pointer to the OcApp object.

See Step 14 of the ObjectWindows tutorial for an example of a program that uses TOleMDIFrame  to create an OLE-enabled decorated MDI frame window.

Public Constructors and Destructors

TOleMDIFrame(const char far* title, TResIdmenuResId, TMDIClient& clientWnd = *new TMDIClient, booltrackMenuSelection = false, TModule* module = 0);

~TOleMDIFrame();

Protected Member Functions

LRESULT DefWindowProc(uint message, WPARAM wParam, LPARAM lParam);

void EvActivateApp(bool active, HTASK hTask);

bool EvOcAppInsMenus(TOcMenuDescr far*);

Response Table Entries

EV_ macros and member functions


See Also

TMDIFrame

TDecoratedMDIFrame

TOleFrame

TOleFrame::SetOcApp


TOleMDIFrame Public Constructor and Destructor

See Also	TOleMDIFrame

Constructor

TOleMDIFrame(const char far* title, TResIdmenuResId, TMDIClient& clientWnd = *new TMDIClient, bool trackMenuSelection = false, TModule* module = 0);

Description

Constructs a TOleMDIFrame object with the indicated title, menu resource ID, client window, and module instance. By default, because trackMenuSelection is false, menu hint text is not displayed. (These parameters coincide with those of TMDIFrame's constructor.)

Destructor

~TOleMDIFrame();

Description

Destroys the OLE MDI frame window object.


See Also

TDecoratedMDIFrame


TOleMDIFrame::DefWindowProc

TOleMDIFrame

Syntax

LRESULT DefWindowProc(uint message, WPARAM wParam, LPARAM lParam);

Description

Allows default processing for all messages except for a resizing message concerning the frame window, in which case, DefWindowProc returns nothing.


TOleMDIFrame::EvOcAppInsMenus

TOleMDIFrame

Syntax

bool EvOcAppInsMenus(TOcMenuDescr far*);

Description

Inserts menus into a provided menu bar, or merges them with a child window and servers. To do this, EvOcAppInsMenus creates a temporary composite menu for the frame and MDI child windows, then copies the shared menu widths to the ObjectComponents structure. It saves the container popups so they can be destroyed later.


TOleMDIFrame::EvActivateApp

TOleMDIFrame

Syntax

void EvActivateApp(bool active, HTASK hTask);

Description

Responds to a message indicating that the frame window of this application (hTask) is going to be either activated (active is true) or deactivated (active is false), and forwards this information to the TOcApp object.


TOleMDIFrame Response Table Entries

TOleMDIFrame

Response table entry	Member function

EV_WM_ACTIVATEAPP	EvActivateApp

EV_OC_APPINSMENUS	EvOcAppInsMenus


TOleView Class

OWL Hierarchy	Inheritance

Header file

oleview.h

Description

Derived from TWindowView and TView, TOleView supports the View half of the Doc/View pair and creates a window with a view that can display an associated document. Documents use views to display themselves to a user. Regardless of whether a view belongs to a server or a container, TOleView sets up a corresponding TOcDocument object (an entire compound document).

In the case of an OLE-enabled container application, view refers to the window where the container application draws the compound document, which may consist of one or more linked and embedded objects. To display these objects in different formats, a container can be associated with more than one view. Similarly, to display the data properly, each embedded object can also have its own view. Each container view creates a corresponding ObjectComponents TOcView object.

If the view belongs to an OLE-enabled server application, TOleView creates a remote view on the server's document (a TOcRemView object). TOleView takes care of transmitting messages from the server to the container, specifically in the case of merging menus and redrawing embedded objects, and supports merging the server's and the container's pop-up menu items to form a composite menu. Because it knows the dimensions of the server's view, TOleView is responsible for telling the container how to redraw the embedded object.

Similarly to TView, TOleView supports the creation of views and provides several event handling functions that allow the view to query, commit, and close views. TOleView  also manages the writing to storage of documents that belong to a container or a server.

Public Constructor and Destructor

TOleView(TDocument& doc, TWindow* parent = 0);

~TOleView();

Public Member Functions

const char far* GetViewname();

TWindow* GetWindow();

bool SetDocTitle(const char far* docname, int index);

static const char far* StaticName();

Protected Member Functions

bool CanClose();

TOcView* CreateOcView(TDocTemplate* tpl, bool isEmbedded, IUnknown* outer);

bool EvOcViewAttachWindow(bool attach);

bool EvOcViewBreakLink(TOcLinkView& view);

bool EvOcViewInsMenus(TOcMenuDescr far& part);

bool EvOcViewClose();

bool EvOcViewLoadPart(TOcSaveLoad far& ocLoad);

bool EvOcViewOpenDoc(const char far*);

bool EvOcViewPartInvalid(TOcPart far& changeInfo);

bool EvOcViewSavePart(TOcSaveLoad far& ocSave);

bool EvOcViewSetLink(TOcLinkView& view);

bool VnDocOpened(int omode);

bool VnInvalidateRect(LPARAM p);

Response Table Entries

EV_ macros and member functions


Storage

A compartment or area within a compound file structure


TOleView Public Constructor and Destructor

TOleView

Constructor

TOleView(TDocument& doc, TWindow* parent = 0);

Description

Constructs a TOleView object associated with the given document object (doc) and parent window (parent).

Destructor

~TOleView();

Description

Destroys the TOleView object and detaches the view from the associated document.


TOleView::GetViewName

TOleView

Syntax

const char far* GetViewName();

Description

Overrides TView's virtual GetViewName function and returns the name of the class (TOleView).


TOleView::GetWindow

TOleView

Syntax

TWindow* GetWindow();

Description

Overrides TView's virtual GetWindow function and returns the TWindow instance associated with this view.


TOleView::SetDocTitle

See Also	TOleView

Syntax

bool SetDocTitle(const char far* docname, int index);

Description

Overrides TView's and TWindow's virtual SetDocTitle function and stores the title of the document associated with this view.


See Also

TView::SetdocTitle

TWindow::SetdocTitle


TOleView::StaticName

See Also	TOleView

Syntax

static const char far* StaticName();

Description

Returns the constant string "Ole View" that is displayed in the user interface selection box.


See Also

TListView::StaticName


TOleView::CanClose

TOleView

Syntax

bool CanClose();

Description

A view uses this function to verify whether or not it can shut down. If this is a server's view window, CanClose checks to see if any open-editing is occurring on any of the embedded objects in the frame window.  If so, CanClose closes this open-editing session by disconnecting the embedded object from its server. Then, it hides the server's frame window and returns true when appropriate.  If this is a container, CanClose queries all documents and views and returns true when all documents and views can be closed.


open-editing

Unlike in-place editing, which takes place in the container's window, open-editing occurs in the server's frame window.


TOleView::CreateOcView

TOleView

Syntax

TOcView* CreateOcView(TDocTemplate* tpl, bool isEmbedded, IUnknown* outer);

Description

Creates an ObjectComponents view associated with the embedded object. Associates the view with the document template specified in tpl. The isEmbedded parameter is true if the view is an embedded object. The outer parameter refers to the IUnknown interface with which the view will aggregate itself.


TOleView::EvOcViewPartInvalid

TOleView

Syntax

bool EvOcViewPartInvalid(TOcPart far& changeInfo);

Description

Notifies the active view of any changes made to the embedded object's data (changeInfo).  Also, notifies any other views associated with this document that the bounding rectangle for the document is invalid and needs to be repainted. EvOcViewPartInvalid always returns true.


TOleView::EvOcViewLoadPart

TOleView

Syntax

bool EvOcViewLoadPart(TOcSaveLoad far& ocLoad);

Description

Asks the server to load itself from storage. Loads the document and its associated view.


TOleView::EvOcViewInsMenus

See Also	TOleView

Syntax

bool EvOcViewInsMenus(TOcMenuDescr far& sharedMenu);

Description

Inserts the server's menu into the composite menu. Determines the number of groups and the number of pop-up menu items to insert within each group. The shared menu (sharedMenu) is the container's menu merged with the server's menu groups.


See Also

TMenuDescr has more information about menu merging.

TOcMenuDescr struct


TOleView::EvOcViewClose

See Also	TOleView

Syntax

bool EvOcViewClose();

Description

Asks the server to close the view associated with this document. Tests to see if the document has been changed since it was last saved. Returns true if the document and its associated view are closed.


See Also

TOleView::EvOcViewSavePart


TOleView::EvOcViewSavePart

See Also	TOleView

Syntax

bool EvOcViewSavePart(TOcSaveLoad far& ocSave);

Description

Asks the server to save the embedded object's data to storage. To save the object, EvOcViewSavePart calls upon the TOleDocument object, which creates storage as necessary for each embedded object. Saves the dimensions of the server's view, which the server uses to tell the container how to redraw the embedded object in the container's window.


See Also

TOleView::EvOcViewClose

TOleView::EvOcViewOpenDoc

TOleDocument


TOleView::EvOcViewOpenDoc

See Also	TOleView

Syntax

bool EvOcViewOpenDoc(const char far* path);

Description

Asks the container application to open an existing document so the document can receive embedded and linked objects. (Actually, TOleView calls on the TOleDocument object to read the document from storage, using the standard OLE IStorage and IStream interfaces). Assigns a unique string identifier to the document and returns true if successful.


See Also

TOleView::EvOcViewClose


TOleView::EvOcViewAttachWindow

TOleView

Syntax

bool EvOcViewAttachWindow(bool attach);

Description

Attaches this view to its ObjectWindows parent window so the embedded object can be either opened and edited or deactivated. To attach a view to an embedded object, set the attach parameter to true. To detach the embedded object, set the attach parameter to false.


TOleView::EvOcViewBreakLink

See Also	TOleView

Syntax

bool EvOcViewBreakLink(TOcLinkView& view);

Description

Responds to an OC_VIEWBREAKLINK message that TOcLinkView sends when the server document that provides the link shuts down. EvOcViewBreakLink breaks the link with a server document or a selection by deleting the TOleLinkView associated with the TOcLinkView (view). After the link is broken, the container application is left holding a static representation (that is, a metafile) of the linked document. Returns false if unsuccessful.

Non-Doc/View applications use TOleWindow's implementation of this function.


See Also

TOleWindow::EvOcViewBreakLink

TOleView::EvOcViewSetLink


TOleView::EvOcViewSetLink

See Also	TOleView

Syntax

bool EvOcViewSetLink(TOcLinkView& view);

Description

Responds to an OC_VIEWSETLINK message TOcLinkView sends when the server document provides a link to a container document. EvOcViewSetLink establishes the link between a TOleLinkView and a TOcLinkView. The view parameter references the view with which the document or selection is associated. Returns false if unsuccessful.

Non-Doc/View applications use TOleWIndow's implementation of the function.


See Also

TOleView::EvOcViewBreakLink

TOleWindow::EvOcViewSetLink


TOleView::VnDocOpened

TOleView

Syntax

bool VnDocOpened(int omode);

Description

Ensures that TOleView's data members, such as DragPart, Pos, and Scale, are initialized properly after a revert operation, which cancels any changes made to the document since the last time the document was saved to storage.


TOleView::VnInvalidateRect

TOleView

Syntax

bool VnInvalidateRect(LPARAM p);

Description

Invalidates the view region specified by p. Use this function to invalidate the bounding rectangle surrounding an embedded object if the object has been changed, usually as a result of in-place editing. If successful, returns true.


TOleView_Response Table Entries
TOleView Response Table Entries

TOleView

Response table entry	Member function

EV_OC_VIEWOPENDOC	EvOcViewOpenDoc

EV_OC_VIEWINSMENUS	EVOcViewInsMenus

EV_OC_VIEWCLOSE	EvOcViewClose

EV_OC_VIEWSAVEPART	EvOcViewSavePart

EV_OC_VIEWLOADPART	EvOcViewLoadPart

EV_OC_VIEWATTACHWINDOW	EvOcViewAttachWindow

EV_OC_VIEWBREAKLINK	EvOcViewBreakLink

EV_OC_VIEWSETLINK	EvOcViewSetLink


TOleWindow Class

See Also	OWL Hierarchy	Inheritance

Header File

olewindo.h

Description

Derived from TWindow, TOleWindow provides support for embedding objects in a compound document and serves as the client of a frame window. A compound document, such as the one TOleWindow supports, can contain many different types of embedded objects, from spreadsheets to bitmaps.  In addition to providing support for a variety of basic window operations, TOleWindow also implements several OLE-related operations, among them

Responding to drag and drop events

In-place editing (the process whereby an embedded object can be edited without having to switch to its associated server application)

Activating an embedded object's server application

Creating views for the container application

Transmitting a document's scaling information between a container's and a server's view windows

TOleWindow has the ability to determine whether it's acting as a server or a container. If it is a container, TOleWindow has a pointer to a TOcView or if it is a server, TOleWindow establishes a pointer to a TOcRemView.  From the server's point of view, every remote view has a corresponding TOleWindow.

Through its many event-handling member functions, TOleWindow communicates with ObjectComponents to implement container and server support for embedded objects, update views, and respond to a variety of menu commands associated with the typical command identifiers (for example, CM_FILEMENU). It also supports OLE-specific verbs such as those activated from the Edit menu (for example, Edit and Open). These commands and verbs can originate from various sources such as a menu selection, a radio button, or even an internal program message.

Conversely, ObjectComponents talks to ObjectWindows by means of the various EV_OC_Xxxx messages. Some of these messages, such as EV_OC_VIEWPARTINVALID, implement container support while others, such as EV_OC_VIEWCLOSE, implement server support.

For any user-defined classes derived from TOleWindow, you need to choose which functions are appropriate. If you want to provide additional server support, you need to define only those functions that implement server messages; if you want to provide container support, you need to define only those functions that provide additional container support.

For example, the data embedded in the container application (a compound document having one or more embedded objects) and the data embedded in the server application (a single OLE object with or without other embedded objects) can be written to storage and loaded  from storage. If you're using TOleWindow without TOleView, you have to manipulate the storage by talking directly to the ObjectComponents class, TOcDocument.

In addition to communicating with ObjectComponents classes, TOleWindow supports many transactions as a result of its interaction with other ObjectWindows classes. By virtue of its derivation from TWindow, naturally it inherits much of TWindow's functionality.

Public Constructor and Destructor

TOleWindow(TWindow* parent = 0, TModule* module = 0);

~TOleWindow();

Public Member Functions

virtual bool Deactivate();

TOcApp* GetOcApp();

TOcDocument* GetOcDoc();

TOcRemView* GetOcRemView();

TOcView* GetOcView();

bool HasActivePart();

virtual void PaintMetafile(TDC& dc, bool erase, TRect& rect);

Protected Data Members

string ContainerName;

TDC* DragDC;

TUIHandle::TWhere DragHit;

TOcPart* DragPart;

TPoint DragPt;

TRect DragRect;

TPoint DragStart;

bool Embedded;

TOcApp* OcApp;

TOcDocument* OcDoc;

TOcView* OcView;

TRect Pos;

TOcScaleFactor Scale;

bool ShowObjects;

Protected Member Functions

bool CanClose();

void CeEditConvert(TCommandEnabler&);

void CeEditCopy(TCommandEnabler&);

void CeEditCut(TCommandEnabler&);

void CeEditDelete(TCommandEnabler&);

void CeEditInsertObject(TCommandEnabler&);

void CeEditLinks(TCommandEnabler&);

void CeEditObject(TCommandEnabler&);

void CeEditPaste(TCommandEnabler&);

void CeEditPasteLink(TCommandEnabler&);

void CeEditPasteSpecial(TCommandEnabler&);

void CeEditVerbs(TCommandEnabler& ce);

void CeFileClose(TCommandEnabler& ce);

void CleanupWindow();

void CmEditConvert();

void CmEditCopy();

void CmEditCut();

void CmEditDelete();

void CmEditInsertObject();

void CmEditLinks();

void CmEditPaste();

void CmEditPasteLink();

void CmEditPasteSpecial();

void CmFileClose(); T

virtual TOcView* CreateOcView(TDocTemplate* tpl, bool isEmbedded, IUnknown* outer)

TPopupMenu* CreateVerbPopup(const TOcVerb& ocVerb);

LRESULT EvCommand(uint id, HWND hWndCtl, uint notifyCode);

void EvCommandEnable(TCommandEnabler& commandEnabler);

void EvDoVerb(uint whichVerb);

void EvLButtonDblClk(uint modKeys, TPoint& point);

void EvLButtonDown(uint modKeys, TPoint&);

void EvLButtonUp(uint modKeys, TPoint&);

void EvMDIActivate(HWND hWndActivated, HWND hWndDeactivated);

void EvMouseMove(uint, TPoint&);

LRESULT EvOcEvent(WPARAM wParam, LPARAM lParam);

bool EvOcPartInvalid(TOcPart far&);

bool EvOcViewAttachWindow(bool attach);

bool EvOcViewBorderSpaceReq(TRect far*);

bool EvOcViewBorderSpaceSet(TRect far*);

bool EvOcViewBreakLink(TOcLinkView& view);

HANDLE EvOcViewClipData(TOcFormat far& format);

bool EvOcViewClose();

bool EvOcViewDrag(TOcDragDrop far&);

bool EvOcViewDrop(TOcDragDrop far&);

bool EvOcViewGetPalette(LOGPALETTE far* far* palette);

bool EvOcViewGetScale(TOcScaleFactor& scaleFactor); IUnknown* outer);

bool EvOcViewGetSiteRect(TRect far* rect);

bool EvOcViewInsMenus(TOcMenuDescr far&);

bool EvOcViewLoadPart(TOcSaveLoad far* ocLoad);

bool EvOcViewOpenDoc(const char far*);

bool EvOcViewPaint(TOcViewPaint far&);

bool EvOcViewPartActivate(TOcPart& ocPart);

bool EvOcViewPartInvalid(TOcPart far& changeInfo);

bool EvOcViewPartSize(TRect far*);

bool EvOcViewSavePart(TOcSaveLoad far& ocSave);

bool EvOcViewScroll(TOcScrollDir);

bool EvOcViewSetLink(TOcLinkView& view);

bool EvOcViewSetScale(TOcScaleFactor& scaleFactor);

bool EvOcViewSetSiteRect(TRect far* rect);

bool EvOcViewSetTitle(const char far* title);

bool EvOcViewShowTools(TOcToolBarInfo far& tbi);

const char far* EvOcViewTitle();

void EvPaint();

void EvRButtonDown(uint modKeys, TPoint& point);

bool EvSetCursor(HWND, uint, uint);

void EvSetFocus(HWND hWndLostFocus);

void EvSize(uint sizeType, TSize& size);

virtual void GetInsertPosition(TRect& rect);

virtual void GetLogPerUnit(TSize& logPerUnit);

void Init();

virtual void InvalidatePart(TOcInvalidate invalid);

virtual bool PaintParts(TDC& dc, bool erase, TRect& rect, bool metafile);

virtual bool PaintSelection(TDC& dc, bool erase, TRect& rect, void* userData = 0);

virtual bool Select(uint modKeys, TPoint& point);

bool SelectEmbedded();

virtual void SetScale(uint16 percent);

void SetSelection(TOcPart* part);

virtual void SetupDC(TDC& dc, bool scale = true);

void SetupWindow();

bool VnInvalidateRect(LPARAM p);

Response Table Entries

EV_ macros and member functions


See Also

TWindowView


Storage

A compartment or area within a larger, logically-related file structure.


TOleWindow Public Constructor and Destructor

TOleWindow

Constructor Syntax

TOleWindow(TWindow* parent = 0, TModule* module = 0);

Description

Constructs a TOleWindow object associated with the specified parent window and module instance.

Destructor Syntax

~TOleWindow();

Description

Checks to see if there are any open views, and, if no open views exist, destroys the TOleWindow object.


TOleWindow::EvOcViewAttachWindow

TOleWindow

Syntax

bool EvOcViewAttachWindow(bool attach);

Description

Attaches the view to its ObjectWindows parent window so that the user can perform open editing on the embedded object, or if the embedded object has been de-activated while in-place editing was occurring.

If the TOleWindow object is unable to handle the message, EvOcViewAttachWindow returns false.


TOleWindow::GetLogPerUnit

TOleWindow

Syntax

virtual void GetLogPerUnit(TSize& logPerUnit);

Description

Gets the logical units (typically pixels) per inch for a document so that the document's embedded objects can be painted correctly on the screen device context.


TOleWindow::CreateVerbPopup

See Also	TOleWindow

Syntax

TPopupMenu* CreateVerbPopup(const TOcVerb& ocVerb);

Description

Creates and enables a pop-up menu option (ocVerb) on the Edit menu. The verb describes an action (for example, Edit, Open, Play) that is appropriate for the embedded object.


See Also

EvDoVerb


TOleWindow::EvDoVerb

See Also	TOleWindow

Syntax

void EvDoVerb(uint whichVerb);

Description

Executes an OLE-related menu option from the Edit menu (for example, Edit, Copy, or Play) that is associated with the selected object.


See Also

CreateVerbPopup


TOleWindow::Init

TOleWindow

Syntax

void Init();

Description

Initializes the TOleWindow object with the appropriate window style and initializes the necessary data members (for example, sets the accelerator ID to IDA_OLEVIEW).


TOleWindow::SelectEmbedded

TOleWindow

Syntax

bool SelectEmbedded();

Description

Selects the embedded object and returns true to indicate that the object has been selected.


TOleWindow::CreateOcView

See Also	TOleWindow

Syntax

virtual TOcView* CreateOcView(TDocTemplate* tpl, bool isEmbedded, IUnknown* outer);

Description

Creates an ObjectComponents view associated with the embedded object. Associates the view with the document template specified in tpl. If isEmbedded is true, a remote view is created (that is, a TOcRemView instead of a TOcView). The outer parameter refers to the IUnknown interface with which the view will aggregate itself.


See Also

TOcView

TOcRemView


TOleWindow::EvOcViewGetSiteRect

See Also	TOleWindow

Syntax

bool EvOcViewGetSiteRect(TRect far* rect);

Description

Gets the size of the rectangle (the site) where the embedded object is to be placed. rect refers to the size of the bounding rectangle that encloses the embedded object.


See Also

EvOcViewSetSiteRect


TOleWindow::EvOcViewSetSiteRect

SeeAlso	TOleWindow

Syntax

bool EvOcViewSetSiteRect(TRect far* rect);

Description

Converts the rect to logical units. This area, referred to as the site, is measured in logical units that take into account any scaling factor. rect refers to the size of the bounding rectangle that encloses the embedded object.


See Also

EvOcViewGetSiteRect


TOleWindow::EvOcViewSetTitle

TOleWindow

Syntax

bool EvOcViewSetTitle(const char far* title);

Description

Sets the window's caption to title. The new caption is the name of the in-place active server merged with the caption of the container's window. In the case of an MDI child window, the new caption is the in-place server's name merged with the caption of the MDI child window. When the child window is maximized, the merged caption is appended to the end of the main frame window's caption.


TOleWindow::Deactivate

TOleWindow

Syntax

virtual bool Deactivate();

Description

If an embedded object is no longer the active embedded object, either because the user has ended an in-place editing session or because the user has clicked outside the embedded object, call Deactivate to unselect the object. Returns true if successful.


TOleWindow::GetInsertPosition

TOleWindow

Syntax

virtual void GetInsertPosition(TRect& rect);

Description

Gets the position (rect) where the embedded object is inserted. You need to override this function if you want to override any default position.


TOleWindow::GetOcView

See Also	TOleWindow

Syntax

TOcView* GetOcView();

Description

Points to the ObjectComponents container view associated with this window. The container view holds the compound document (that is a document containing one or more embedded objects).


See Also

TOcView


TOleWindow::GetOcRemView

See Also	TOleWindow

Syntax

TOcRemView* GetOcRemView();

Description

Returns the server's view associated with this window. In order to draw the OLE object in the container's window, the server creates a remote view.


See Also

TOcRemView


TOleWindow::GetOcApp

See Also	TOleWindow

Syntax

TOcApp* GetOcApp();

Description

Returns the ObjectComponents application associated with this window. Every ObjectComponents application that supports linking and embedding has an associated TOcApp object.


See Also

TOcApp


TOleWindow::GetOcDoc

See Also	TOleWindow

Syntax

TOcDocument* GetOcDoc();

Description

Returns the ObjectComponents document associated with this window. This document can be either a container's or a server's document.  If this is a TOcDocument created by the container, the document is an entire compound document, which may consist of one or more embedded objects. If this is a TOcDocument created by the server, the document is a single OLE object's data.


See Also

TOcDocument


TOleWindow::HasActivePart

See Also	TOleWindow

Syntax

bool HasActivePart();

Description

Returns true if the container's view holds an in-place active embedded object.


See Also

TOcView::GetActivePart

InvalidatePart


TOleWindow::InvalidatePart

See Also	TOleWindow

Syntax

virtual void InvalidatePart(TOcInvalidate invalid);

Description

Invalidates the area where the embedded object exists. The server uses this function to tell OLE that the part (the embedded object), has changed. OLE then asks the server to redraw the part into a new metafile so that OLE can redraw the object for the container application even when the server application is not active.


See Also

PaintMetafile

TOcView_GetActivePart


TOleWindow::PaintParts

TOleWindow

Syntax

virtual bool PaintParts(TDC& dc, bool erase, TRect& rect, bool metafile);

Description

Repaints the embedded objects on the given device context. The erase parameter is true if the background of the embedded object is to be repainted. rect indicates the area that needs repainting. metafile indicates whether or not the device context represents a metafile.


TOleWindow::PaintSelection

TOleWindow

Syntax

virtual bool PaintSelection(TDC& dc, bool erase, TRect& rect, void* userData = 0);

Description

Repaints the selected portion of a document on the given device context. The parameter userData, which TocDataProvider passes to the application, contains information the application uses to repaint the selection. Similar to a moniker, this information tells the application where to find the selection and how to repaint it.


See Also

PaintParts

TOleLinkView


TOleWindow::PaintMetafile

See Also	TOleWindow

Syntax

virtual void PaintMetafile(TDC& dc, bool erase, TRect& rect);

Description

Repaints the area of the server where the embedded object resides. The dc parameter points to the device context. erase is true if the background of the embedded object is to be repainted. rect refers to the area to be repainted.


See Also

InvalidatePart


TOleWindow::Select

TOleWindow

Syntax

virtual bool Select(uint modKeys, TPoint& point);

Description

Selects the embedded object at the specified point (measured in logical units). Returns true if the object is captured by the mouse drag; otherwise, returns false.


TOleWindow::DragPart

TOleWindow

Syntax

TOcPart* DragPart;

Description

Points to the embedded object (the part) being dragged.


TOleWindow::DragHit

See Also	TOleWindow

Syntax

TUIHandle::TWhere DragHit;

Description

Indicates the position in the embedded object where the user points and clicks the mouse. This can be any one of the TUIHandle::TWhere enumerated values, for example, TopLeft, TopCenter, TopRight, MidLeft, MidCenter, MidRight, BottomLeft, BottomCenter, BottomRight, or Outside when no dragging is taking place.


See Also:

TUIHandle::TWhere enum


TOleWindow::DragDC

See Also	TOleWindow

Syntax

TDC* DragDC;

Description

Points to the device context used while an object is being dragged.


See Also

DragPt


TOleWindow::DragPt

See Also	TOleWindow

Syntax

TPoint DragPt;

Description

Indicates the point (in logical units) where the mouse is over the dragged object.


See Also

DragDC


TOleWindow::DragRect

See Also	TOleWindow

Syntax

TRect DragRect;

Description

Holds the rectangle being dragged.


See Also

DragDC


TOleWindow::DragStart

See Also	TOleWindow

Syntax

TPoint DragStart;

Description

Holds the point where the dragging of the embedded object began.


See Also

DragPt


TOleWindow::Embedded

TOleWindow

Syntax

bool Embedded;

Description

Is true if this TOleWindow is an embedded window. As a result, a TocRemView is created because the data is being displayed in a server's window.


TOleWindow::OcDoc

See Also	TOleWindow

Syntax

TOcDocument* OcDoc;

Description

Holds the ObjectComponents document associated with this TOleWindow.


See Also

TOcDocument

TOcView::OcDocument


TOleWindow::OcView

See Also	TOleWindow

Syntax

TOcView* OcView;

Description

Holds the ObjectComponents view or remote view (the server's) associated with the TOleWindow view.


See Also

TOcView


TOleWindow::OcApp

See Also	TOleWindow

Syntax

TOcApp* OcApp;

Description

Holds the ObjectComponents application associated with this TOleWindow.


See Also

TOcView::OcApp

TOcApp


TOleWindow::Pos

TOleWindow

Syntax

TRect Pos;

Description

Holds the current area in the window where the object is embedded.  Pos reflects the area where the object is moved if you move the object.


TOleWindow::ContainerName

TOleWindow

Syntax

string ContainerName;

Description

Holds the name of the container. The server displays the container's name when an embedded object is being edited in the server's window (referred to as out-of-place editing).


TOleWindow::Scale

See Also	TOleWindow

Syntax

TOcScaleFactor Scale;

Description

Holds the current scaling factor. The server uses this information to determine how to scale the document.


See Also

TOcScaleFactor

EvOcViewGetScale

SetScale


TOleWindow::ShowObjects

TOleWindow

Syntax

bool ShowObjects;

Description

Is true if the embedded object's frame (the gray or shaded brushes around the object) is displayed. The frame can be turned on or off depending on how you want the object to appear.


TOleWindow::EvOcViewGetScale

See Also	TOleWindow

Syntax

bool EvOcViewGetScale(TOcScaleFactor& scaleFactor);

Description

Responds to an OC_VIEWGETSCALE message and gets the scaling for the server object, causing the embedded object to be displayed using the correct scaling value (for example, 120%). scaleFactor indicates the scaling factor, the ratio between the size of the embedded object and the size of the site where the object is to be displayed.

If the TOleWindow object is unable to handle the message, EvOcViewGetScale returns false.


See Also

Scale

TOcScaleFactor


TOleWindow::EvOcViewSetScale

See Also	TOleWindow

Syntax

bool EvOcViewSetScale(TOcScaleFactor& scaleFactor);

Description

Responds to an OC_VIEWSETSCALE message and handles the scaling for server application, ensuring that the embedded object is displayed using the correct scaling values (for example, 120%). The server uses this value in its paint procedure when the embedded object needs to be redrawn. scaleFactor indicates the scaling factor, the ratio between the size of the embedded object and the size of the site where the object is to be displayed.

If the TOleWindow object is unable to handle the message, EvOcViewSetScale returns false.


See Also

EvOcViewGetScale

TOcScaleFactor


TOleWindow::SetupDC

See Also	TOleWindow

Syntax

virtual void SetupDC(TDC& dc, bool scale = true);

Description

Determines the viewport's origin and extent (the logical coordinates and the size of the device context). Sets up the device context (DC) before painting the embedded object. dc refers to the DC and scale indicates that the scaling factor to use when painting the embedded object is a ratio between the site and the embedded object.


See Also

TOcScaleFactor

SetScale


TOleWindow::SetScale

See Also	TOleWindow

Syntax

virtual void SetScale(uint16 percent);

Description

Sets the ratio of the embedded object's size to the size of the site.


See Also

SetupDC


The area inside the container where the embedded object will be drawn


TOleWindow::CanClose

TOleWindow

Syntax

bool CanClose();

Description

Returns true if the window can be closed. Checks all the server's child windows' CanClose functions, which must return true before the window can be closed. Terminates any open editing transactions before closing the window; otherwise, passes control to TWindow::CanClose.


TOleWindow::CeEditConvert

TOleWindow

Syntax

void CeEditConvert(TCommandEnabler&);

Description

Enables a command with an ID of CM_EDITCONVERT, which lets the user convert the selected object from one format to another. This is an OLE-specific pop-up menu option.


TOleWindow::CeEditCopy

TOleWindow

Syntax

void CeEditCopy(TCommandEnabler&);

Description

Enables a command with an ID of CM_EDITCOPY, which lets the user copy selected object to the clipboard.


TOleWindow::CeEditCut

TOleWindow

Syntax

void CeEditCut(TCommandEnabler&);

Description

Enables a command with an ID of CM_EDITCUT, which lets a user copy and delete the selected object from the view.


TOleWindow::CeEditDelete

TOleWindow

Syntax

void CeEditDelete(TCommandEnabler&);

Description

Enables a command with an ID of CM_EDITDELETE, which lets the user delete the selected object from the view.


TOleWindow::CeEditInsertObject

TOleWindow

Syntax

void CeEditInsertObject(TCommandEnabler&);

Description

Enables a command with an ID of CM_EDITCUT, which lets the user cut a section of text from the view.


TOleWindow::CeEditLinks

TOleWindow

Syntax

void CeEditLinks(TCommandEnabler&);

Description

Enables a command with an ID of CM_EDITLINKS, which lets the user manually update the list of linked items in the current view.


TOleWindow::CeEditObject

TOleWindow

Syntax

void CeEditObject(TCommandEnabler&);

Description

Enables a command with an ID of CM_EDITOBJECT, which lets the user edit the embedded object.


TOleWindow::CeEditPaste

TOleWindow

Syntax

void CeEditPaste(TCommandEnabler&);

Description

Enables a command with an ID of CM_EDITPASTE, which lets the user paste the embedded object from the clipboard.


TOleWindow::CeEditPasteLink

See Also	TOleWindow

Syntax

void CeEditPasteLink(TCommandEnabler&);

Description

Enables a PasteLink command with an ID of CM_EDITPASTELINK, which lets the user link to the embedded object on the clipboard. See the ocrxxxx Clipboard Constants for a description of the available clipboard formats.


See Also

TOleWindow::CeEditPasteSpecial

ocrxxxx Clipboard Constants


TOleWindow::CeEditPasteSpecial

See Also	TOleWindow

Syntax

void CeEditPasteSpecial(TCommandEnabler&);

Description

Enables the PasteSpecial command, which lets the user select a clipboard format to be pasted or paste linked.  See the ocrxxxx Clipboard Constants for a description of the available clipboard formats.-


See Also

TOleWindow::CeEditPasteLink

ocrxxxx Clipboard Constants


TOleWindow::CeEditVerbs

TOleWindow

Syntax

void CeEditVerbs(TCommandEnabler& ce);

Description

Enables the Edit|Verbs command, which lets the user select one of the OLE-specific verbs from the Edit menu: for example, Edit, Open, or Play.


TOleWindow::CeFileClose

TOleWindow

Syntax

void CeFileClose(TCommandEnabler& ce);

Description

Enables the FileClose command, which lets the user exit from the window view.


TOleWindow::CleanupWindow

See Also	TOleWindow

Syntax

void CleanupWindow();

Description

Performs normal window cleanup and informs the TOcView object that the window is closed.


See Also

TWindow::CleanupWindow

TOcView


TOleWindow::CmEditConvert

TOleWindow

Syntax

void CmEditConvert();

Description

Responds to a command with an ID of CM_EDITCONVERT by converting an object from one type to another.


TOleWindow::CmEditCopy

TOleWindow

Syntax

void CmEditCopy();

Description

Responds to a command with an ID of CM_EDITCOPY by copying the selected text to the clipboard.


TOleWindow::CmEditCut

TOleWindow

Syntax

void CmEditCut();

Description

Responds to a command with an ID of CM_EDITCUT by copying the selected text to the clipboard before cutting the text.


TOleWindow::CmEditDelete

TOleWindow

Syntax

void CmEditDelete();

Description

Responds to a command with an ID of CM_EDITDELETE by deleting the selected text.


TOleWindow::CmEditInsertObject

TOleWindow

Syntax

void CmEditInsertObject();

Description

Responds to a command with an ID of CM_EDITINSERTOBJECT by inserting an object that a user selects from a list of object types.


TOleWindow::CmEditLinks

TOleWindow

Syntax

void CmEditLinks();

Description

Responds to a command with an ID of CM_EDITLINKS by updating the user-selected list of linked items in the current view.


TOleWindow::CmEditPaste

TOleWindow

Syntax

void CmEditPaste();

Description

Responds to a command with an ID of CM_EDITPASTE by pasting an object from the clipboard into the document.


TOleWindow::CmEditPasteLink

See Also	TOleWindow

Syntax

void CmEditPasteLink();

Description

Responds to a command with an ID of CM_EDITPASTELINK by creating a link between the current document and the object on the clipboard.


See Also

TOleWindow::CmEditPasteSpecial

ocrxxxx Clipboard Constants


TOleWindow::CmEditPasteSpecial

See Also	TOleWindow

Syntax

void CmEditPasteSpecial();

Description

Responds to a command with an ID of CM_EDITPASTESPECIAL by letting the user select an object from a list of available formats for pasting from the clipboard onto the document.


See Also

TOleWindow::CmEditPasteLink

ocrxxxx Clipboard Constants


TOleWindow::CmFileClose

TOleWindow

Syntax

void CmFileClose();

Description

Responds to a command with an ID of CM_FILECLOSE by posting a WM_CLOSE message to the parent window to close the application.


TOleWindow::EvCommand

See Also	TOleWindow

Syntax

LRESULT EvCommand(uint id, HWND hWndCtl, uint notifyCode);

Description

Overrides the usual EvCommand message to handle the OLE verbs from CM_EDITFIRSTVERB to CM_EDITLASTVERB. These commands, which are defined in oleview.rh, correspond to the OLE-specific Edit menu selections such as Edit, Open, and Play. All of the other commands are passed to TWindow::EvCommand for normal processing.


See Also

CM_xxxx Edit View Constants

TOleWindow::EvCommandEnable

TWindow::EvCommand


TOleWindow::EvCommandEnable

See Also	TOleWindow

Syntax

void EvCommandEnable(TCommandEnabler& commandEnabler);

Description

Overrides the usual EvCommandEnable message in order to enable the OLE verbs from CM_EDITFIRSTVERB to CM_EDITLASTVERB. These commands enable the OLE-specific Edit menu selections, such as Edit, Open, and Play. Many of the other commands are passed to TWindow::EvCommand for normal processing.

If a window is embedded, however, TOleWindow calls upon TWindow's RouteCommandEnable to perform command enabling.


See Also

TOleWindow::EvCommand

TWindow::EvCommand

TWindow::RouteCommandEnable


TOleWindow::EvRButtonDown

See Also	TOleWindow

Syntax

void EvRButtonDown(uint modKeys, TPoint& point);

Description

Responds to a right button down message. Performs additional hit testing to see which embedded object, if any, is being clicked on and displays a local menu with appropriate options for the embedded object.

point refers to the place where the mouse is located. modKeys holds the values for a combined key and transaction, such as a Shift+Double-click of the mouse button.


See Also

EvLButtonDown


TOleWindow::EvLButtonUp

TOleWindow

Syntax

void EvLButtonUp(uint modKeys, TPoint& point);

Description

Responds to a left button up message by ending a mouse drag action. point refers to the place where the mouse is located. modKeys holds the values for a combined key and mouse transaction.


TOleWindow::EvLButtonDown

TOleWindow

Syntax

void EvLButtonDown(uint modkeys, TPoint& point);

Description

Responds to a left button down message by beginning a mouse drag transaction at the given point. Performs additional hit testing to see which embedded object, if any, is being clicked on. The modKeys parameter holds the values for a key combination such as a shift and double click of the mouse button.

See also EvRButtonDown


TOleWindow::EvLButtonDblClk

TOleWindow

Syntax

void EvLButtonDblClk(uint modKeys, TPoint& point);

Description

Responds to a mouse button double click message. EvLButtonDblClk performs hit testing to see which embedded object, if any, is being clicked on, then in-place activates the embedded object.


TOleWindow::VnInvalidateRect

TOleWindow

Syntax

bool VnInvalidateRect(LPARAM p);

Description

When the embedded object is modified, VnInvalidateRect sends a message to the View portion of the Doc/View pair. When TOleWindow receives this message, the view region is marked for erasing. VnInvalidateRect always returns true.


TOleWindow::EvMDIActivate

See Also	TOleWindow

Syntax

void EvMDIActivate(HWND hWndActivated, HWND hWndDeactivated);

Description

Responds to a message forwarded from the MDI child window (if one exists) and lets the TOcView class know that the view window child window frame has been activated or deactivated.

The hWndActivated parameter contains a handle to the MDI child window being activated. Both the child window being activated being activated and the child window (hWndDeactivated) being deactivated receive this message.


See Also

TOcView


TOleWindow::EvMouseMove

TOleWindow

Syntax

void EvMouseMove(uint, TPoint& point);

Description

Responds to a mouse move message with the appropriate transaction. If the mouse is being dragged, the embedded object is moved. If a resizing operation occurs, then the embedded object is resized. This message is handled only when a mouse dragging or resizing action involving the embedded object occurs.


TOleWindow::EvOcEvent

TOleWindow

Syntax

LRESULT EvOcEvent(WPARAM wParam, LPARAM lParam);

Description

Responds to a WM_OCEVENT message and subdispatches the message based on wParam. ObjectComponents sends WM_OCEVENT messages when it needs to communicate with an OLE-generated event; for example, if a server wants to display toolbars.


TOleWindow::EvOcPartInvalid

TOleWindow

Syntax

bool EvOcPartInvalid(TOcPart far&);

Description

Handles a WM_OCEVENT message concerning the embedded or linked object in the document and invalidates the part.

If the TOleWindow object is unable to handle the message, EvOcPartInvalid returns false.


TOleWindow::EvOcViewBorderSpaceReq

See Also	TOleWindow

Syntax

bool EvOcViewBorderSpaceReq(TRect far*);

Description

Requests that the server create space for a tool bar in the view of an embedded object.

If the TOleWindow object is unable to handle the message,  EvOcViewBorderSpaceReq returns false, the default value.


See Also

EvOcViewBorderSpaceSet


TOleWindow::EvOcViewBorderSpaceSet

See Also	TOleWindow

Syntax

bool EvOcViewBorderSpaceSet(TRect far*);

Description

Requests that the server's tool bar be placed in the container's view of an embedded object.

If the TOleWindow object is unable to handle the message, EvOcViewBorderSpaceSet returns false, the default value.


See Also

EvOcViewBorderSpaceReq


TOleWindow::EvOcViewBreakLink

See Also	TOleWindow

Syntax

bool EvOcViewBreakLink(TOcLinkView& view);

Description

EvOcViewBreakLink responds to an OC_VIEWBREAKLINK message that TOcLinkView sends when the server document that provides the link shuts down. EvOcViewBreakLink breaks the link with a server document or a selection by deleting the TOleLinkView associated with the TOcLinkView (view). Returns false if unsuccessful. Doc/View applications use TOleView's EvOcViewBreakLink, which overrides TOleWindow's version.


See Also

TOleWindow::EvOcViewSetLink

TOleView::EvOcViewBreakLink


TOleWindow::EvOcViewClipData

See Also	TOleWindow

Syntax

HANDLE EvOcViewClipData(TOcFormat far& format);

Description

Requests clipboard data in the specified format.

If the TOleWindow object is unable to handle the message, EvOcViewClipData returns false.


See Also

ocrxxxx Clipboard Constants

TOcFormat


TOleWindow::EvOcViewClose

TOleWindow

Syntax

bool EvOcViewClose();

Description

Asks the server to close a currently open document and its associated view.

If the TOleWindow object is unable to handle the message, EvOcViewClose returns false.


TOleWindow::EvOcViewDrop

TOleWindow

Syntax

bool EvOcViewDrop(TOcDragDrop far&);

Description

Requests a given object be dropped at a specified place on the container's window.

If the TOleWindow object is unable to handle the message, EvOcViewDrop returns false.


TOleWindow::EvOcViewDrag

TOleWindow

Syntax

bool EvOcViewDrag(TOcDragDrop far&);

Description

Handles an OC_VIEWDRAG message asking the container to provide visual feedback while the user is dragging the embedded object.

If the TOleWindow object is unable to handle the message, EvOcViewDrag returns false.


TOleWindow::EvOcViewGetPalette

TOleWindow

Syntax

bool EvOcViewGetPalette(LOGPALETTE far* far* palette);

Description

Requests the color palette to draw the object.

If the TOleWindow object is unable to handle the message, EvOcViewGetPalette returns false.


TOleWindow::EvOcViewInsMenus

TOleWindow

Syntax

bool EvOcViewInsMenus(TOcMenuDescr far&);

Description

Requests that the menus in a composite menu (a menu composed of both the server's and the container's menus).

If the TOleWindow object is unable to handle the message, EvOcViewInsMenus returns false.


TOleWindow::EvOcViewLoadPart

TOleWindow

Syntax

bool EvOcViewLoadPart(TOcSaveLoad far* ocLoad);

Description

Requests that an embedded object load itself.

If the TOleWindow object is unable to handle the message, EvOcViewLoadPart returns false.


TOleWindow::EvOcViewPaint

TOleWindow

Syntax

bool EvOcViewPaint(TOcViewPaint far&);

Description

Asks the server to paint an object at a given position on a specified device context.

If the TOleWindow object is unable to handle the message, EvOcViewPaint returns false.


TOleWindow::EvOcViewPartActivate

TOleWindow

Syntax

bool EvOcViewPartActivate(TOcPart& ocPart);

Description

Notifies ObjectWindows container applications that an embedded object is active.  ocPart is the embedded object that has been activated. EvOcViewPartActivate returns true after the embedded object has been activated.


TOleWindow::EvOcViewPartInvalid

TOleWindow

Syntax

bool EvOcViewPartInvalid(TOcPart far& changeInfo);

Description

Informs an active container that one of its embedded objects needs to be redrawn. Changes in the container's part should be reflected in any other, non-active views. Returns true after all views have been notified of the necessary changes.

If the TOleWindow object is unable to handle the message, EvOcViewPartInvalid returns false.


TOleWindow::EvOcViewPartSize

TOleWindow

Syntax

bool EvOcViewPartSize(TRect far*);

Description

The server asks itself  the size of its current rectangle and lets the container know about the size of the server's view in pixels.

If the TOleWindow object is unable to handle the message, EvOcViewPartSize returns false.


TOleWindow::EvOcViewScroll

TOleWindow

Syntax

bool EvOcViewScroll(TOcScrollDir);

Description

Asks the container to scroll the view window and updates any internal state as needed. EvOcViewScroll is called when the server is resizing or a drop interaction occurs near the edge of the window.

If the TOleWindow object is unable to handle the message, EvOcViewScroll returns false.


TOleWindow::EvOcViewSetLink

See Also	TOleWindow

Syntax

bool EvOcViewSetLink(TOcLinkView& view);

Description

Responds to an OC_VIEWSETLINK message TOcLinkView sends when the server document provides a link to a container document. EvOcViewSetLink establishes the link between a TOleLinkView and a TOcLinkView. view references the view with which the document or selection is associated. Returns false if unsuccessful.

Doc/View applications use TOleView 's implementation of this function.


See Also

TOleWindow::EvOcViewBreakLink

TOleView::EvOcViewSetLink


TOleWindow::EvOcViewTitle

TOleWindow

Syntax

const char far* EvOcViewTitle();

Description

Asks the container for the caption in its frame window. Returns the frame window's caption.


TOleWindow::EvOcViewSavePart

TOleWindow

Syntax

bool EvOcViewSavePart(TOcSaveLoad far& ocSave);

Description

Asks the server to write an embedded object's data (the part as represented by the ocSave parameter) into storage.

If the TOleWindow object is unable to handle the message, EvOcViewSavePart returns false.


TOleWindow::EvOcViewShowTools

TOleWindow

Syntax

bool EvOcViewShowTools(TOcToolBarInfo far& tbi);

Description

Asks the server to provide its tool bars for display in the container's window. Returns true if tool bars are supplied.

If the TOleWindow object is unable to handle the message,  EvOcViewShowTools returns false.


TOleWindow::EvOcViewOpenDoc

TOleWindow

Syntax

bool EvOcViewOpenDoc(const char far*);

Description

Asks the container to open an existing document, which will be used for linking from the embedding site.

If the TOleWindow object is unable to handle the message,  EvOcViewOpenDoc returns false.


TOleWindow::EvSetCursor

TOleWindow

Syntax

bool EvSetCursor(HWND, uint hitTest, uint);

Description

Performs hit testing to tell where the cursor is located within the window and what object the cursor is moving over. If the cursor is within an embedded object,  EvSetCursor changes the shape of the cursor.

When the cursor is over an inactive part and not on a handle, EvSetCursor uses an arrow cursor. If the cursor is on one of the handles of the embedded part, EvSetCursor changes the cursor to a resizing cursor.


TOleWindow::EvSetFocus

TOleWindow

Syntax

void EvSetFocus(HWND hWndLostFocus);

Description

Responds to a change in focus of the window.  hWndLostFocus contains a handle to the window losing the focus. EvSetFocus checks to see if an in-place server exists and, if so, passes the focus to the in-place server.


TOleWindow::EvSize

See Also	TOleWindow

Syntax

void EvSize(uint sizeType, TSize& size);

Description

Passes the event to TWindow::EvSize for normal processing and forwards the event to TOcView::EvResize to let a possible in-place server adjust  its size.


See also

TOcView::EvSize


TOleWindow::EvPaint

See Also	TOleWindow

Syntax

void EvPaint();

Description

Sets up the dc for proper scaling and scrolling and then calls the derived class's Paint method to paint the contents of the dc.


See Also

TGadget::Paint

TPreviewPage::Paint

TUIHandle::Paint

TWindow::Paint


TOleWindow::SetupWindow

See Also	TOleWindow

Syntax

void SetupWindow();

Description

Establishes a connection between the TOcView object and the view's HWND so the view can send notification messages to the window.


See also

TWindow::SetupWindow

TOcView::SetupWindow


TOleWindow::SetSelection

TOleWindow

Syntax

void SetSelection(TOcPart* part);

Description

Selects the embedded object indicated in the part parameter. When the embedded object is selected, a selection box is drawn around the area. After an embedded object is selected, the user can perform operations on the embedded object: for example, moving, sizing, or copying the embedded object to the clipboard.


TOleWindow Response Table Entries

TOleWindow

Response table entry	Member function

EV_WM_LBUTTONDOWN	EvLButtonDown

EV_WM_RBUTTONDOWN	EvRButtonDown

EV_WM_LBUTTONDBLCLK	EvLButtonDblClk

EV_WM_MOUSEMOVE	EvMouseMove

EV_WM_LBUTTONUP	EvLButtonUp

EV_WM_PAINT	EvPaint

EV_WM_SIZE	EvSize

EV_WM_MDIACTIVATE	EvMDIActivate

EV_WM_SETFOCUS	EvSetFocus

EV_WM_SETCURSOR	EvSetCursor

EV_COMMAND(CM_EDITDELETE, CmEditDelete)	CmEditDelete

EV_COMMAND_ENABLE(CM_EDITDELETE, CeEditDelete)	CeEditDelete

EV_COMMAND(CM_EDITCUT, CmEditCut)	CmEditCut

EV_COMMAND_ENABLE(CM_EDITCUT, CeEditCut)	CeEditCut

EV_COMMAND(CM_EDITCOPY, CmEditCopy)	CmEditCopy

EV_COMMAND_ENABLE(CM_EDITCOPY, CeEditCopy)	CeEditCopy

EV_COMMAND(CM_EDITPASTE, CmEditPaste)	CmEditPaste

EV_COMMAND_ENABLE(CM_EDITPASTE, CeEditPaste)	CeEditPaste

EV_COMMAND(CM_EDITPASTESPECIAL, CmEditPasteSpecial)	CmEditPasteSpecial

EV_COMMAND_ENABLE(CM_EDITPASTESPECIAL, CeEditPasteSpecial)	CeEditPasteSpecial

EV_COMMAND(CM_EDITPASTELINK, CmEditPasteLink)	CmEditPasteLink

EV_COMMAND_ENABLE(CM_EDITPASTELINK, CeEditPasteLink)	CeEditPasteLink

EV_COMMAND(CM_EDITINSERTOBJECT, CmEditInsertObject)	CmEditInsertObject

EV_COMMAND_ENABLE(CM_EDITINSERTOBJECT, CeEditInsertObject)	CeEditInsertObject

EV_COMMAND_ENABLE(CM_EDITLINKS, CeEditLinks)	CeEditLinks

EV_COMMAND(CM_EDITLINKS, CmEditLinks)	CmEditLinks

EV_COMMAND_ENABLE(CM_EDITOBJECT, CeEditObject)	CeEditObject

EV_COMMAND_ENABLE(CM_EDITCONVERT, CeEditConvert)	CeEditConvert

EV_COMMAND(CM_EDITCONVERT, CmEditConvert)	CmEditConvert

EV_COMMAND(CM_EXIT, CmFileClose)	CmFileClose

EV_COMMAND_ENABLE(CM_EXIT, CeFileClose)	CeFileClose

EV_MESSAGE(WM_OCEVENT, EvOcEvent)	EvOcEvent

EV_OWLNOTIFY(vnInvalidate)	VnInvalidateRect

EVOCVIEWPARTACTIVATE	EvOcViewPartActivate

EV_OC_VIEWPARTINVALID	EvOcViewPartInvalid

EV_OC_VIEWSETTITLE	EvOcViewSetTitle

EV_OC_VIEWTITLE	EvOcViewTitle

EV_OC_VIEWBORDERSPACEREQ	EvOcViewBorderSpaceReq

EV_OC_VIEWBORDERSPACESET	EvOcViewBorderSpaceSet

EV_OC_VIEWDROP	EvOcViewDrop

EV_OC_VIEWDRAG	EvOcViewDrag

EV_OC_VIEWSCROLL	EvOcViewScroll

EV_OC_VIEWGETSCALE	EvOcViewGetScale

EV_OC_VIEWGETSITERECT	EvOcViewGetSiteRect

EV_OC_VIEWSETSITERECT	EvOcViewSetSiteRect

EV_OC_VIEWPAINT	EvOcViewPaint

EV_OC_VIEWSAVEPART	EvOcViewSavePart

EV_OC_VIEWLOADPART	EvOcViewLoadPart

EV_OC_VIEWINSMENUS	EvOcViewInsMenus

EV_OC_VIEWSHOWTOOLS,	EvOcViewshowTools

EV_OC_VIEWGETPALETTE	EvOcViewGetPalette

EV_OC_VIEWCLIPDATA,	EvOcViewclipData

EV_OC_VIEWCLOSE	EvOcViewClose

EV_OC_VIEWPARTSIZE	EvOcViewPartSize

EV_OC_VIEWOPENDOC	EvOcViewOpenDoc

EV_OC_VIEWATTACHWINDOW	EvOcViewAttachWindow

EV_OC_VIEWSETSCALE	EvOcViewSetScale

EV_OC_VIEWBREAKLINK	EvOcViewBreakLink

EV_OC_VIEWSETLINK	EvOcViewSetLink


TOpenSaveDialog Class

OWL Hierarchy	Inheritance

Header File

opensave.h

Description

TOpenSaveDialog is the base class for modal dialogs that let you open and save a file under a specified name. TOpenSaveDialog constructs a TData structure and passes it the TOpenSaveDialog constructor. Then the dialog is executed (modal) or created (modeless). Upon return, the necessary fields are updated, including an error field that contains 0, or a common dialog extended error.

Public Constructor

TOpenSaveDialog(TWindow* Parent, TData& data, TResID templateID = 0, const char far* title = 0, TModule* module = 0);

Public Member Functions

static int GetFileTitle(const char far* fileName, char far* fileTitle, int fileTitleLen);

static int GetFileTitleLen(const char far* fileName);

Protected Data Members

TData& Data;

OPENFILENAME ofn;

static uint ShareViMsgId;

Protected Constructor

TOpenSaveDialog(TWindow* Parent, TData& data, TModule* module);

Protected Member Functions

void CmLbSelChanged();

void CmOk();

bool DialogFunction(uint message, WPARAM, LPARAM);

int DoExecute();

void Init(TResId templateId);

virtual int ShareViolation();

Response Table Entries

EV_ macros and member functions

Structures

TData struct


TOpenSaveDialog Public Constructor
TOpenSaveDialog Public Constructors

See Also	TOpenSaveDialog

Syntax

TOpenSaveDialog(TWindow* parent, TData& data, TResId templateId = 0, const char far* title = 0, TModule* module = 0);

Description

Constructs an open save dialog box object with the supplied parent window, data, resource ID, title, and current module object.


See Also

TData struct


TOpenSaveDialog::GetFileTitle

TOpenSaveDialog

Syntax

static int GetFileTitle(const char far* fileName, char far* fileTitle, int fileTitleLen)

Description

Stores the name of the file to be saved or opened.


TOpenSaveDialog::GetFileTitleLen

TOpenSaveDialog

Syntax

static int GetFileTitleLen(const char far* fileName);

Description

Stores the length of the file name to be saved or opened.


TOpenSaveDialog::Data

TOpenSaveDialog

Syntax

TData& Data;

Description

Stores the file name, its length, extension, filter, initial directory, default file name, extension, and any error messages.


TOpenSaveDialog::ofn

See Also	TOpenSaveDialog

Syntax

OPENFILENAME ofn;

Description

Contains the attributes of the file name such as length, extension, and directory. ofn is initialized using the fields in the TOpenSaveDialog::TData class. This member is not available under Presentation Manager.


See Also

TData struct


TOpenSaveDialog::ShareViMsgId

See Also	TOpenSaveDialog

Syntax

static uint ShareViMsgId;

Description

Contains the message ID of the registered ShareViolation message. This member is not available under Presentation Manager.


See Also

TData struct

ShareViolation


TOpenSaveDialog Protected Constructor

See Also	TOpenSaveDialog

Syntax

TOpenSaveDialog(TWindow* parent, TData& data, TModule* module);

Description

Constructs a TOpenSaveDialog box object with the supplied parent, data, and current module object.


See Also

TData struct


TOpenSaveDialog::CmLbSelChanged

TOpenSaveDialog

Syntax

void CmLbSelChanged();

Description

Indicates that the selection state of the file name list box in the GetOpenFileName or GetSaveFileName dialog boxes has changed. CmLbSelChanged is a default handler for command messages sent by lst1 or lst2 (the file and directory list boxes, respectively).


TOpenSaveDialog::CmOk

See Also	TOpenSaveDialog

Syntax

void CmOk();

Description

Responds to a click on the dialog box's OK button (with the identifier IDOK). Calls CloseWindow (passing IDOK).


See Also

TDialog::CloseWindow


TOpenSaveDialog::DialogFunction

TOpenSaveDialog

Syntax

bool DialogFunction(uint message, WPARAM, LPARAM);

Description

Returns true if a message is handled, returns ShareViMsgId if a sharing violation occurs, otherwise returns false.


TOpenSaveDialog::DoExecute

TOpenSaveDialog

Syntax

int DoExecute();

Description

Creates and executes a modal dialog box.


TOpenSaveDialog::Init

TOpenSaveDialog

Syntax

void Init(TResId templateId);

Description

Initializes a TOpenSaveDialog object with the current resource ID.


TOpenSaveDialog::ShareViolation

See Also	TOpenSaveDialog

Syntax

virtual int ShareViolation();

Description

If a sharing violation occurs when a file is opened or saved, ShareViolation is called to obtain a response. The default return value is OFN_SHAREWARN. Other sharing violation responses are listed in the following table. This member is not available under Presentation Manager.

Constant	Meaning

OFN_SHAREFALLTHROUGH	Specifies that the file name can be used and that the dialog box should return it to the application.

OFN_OFN_SHARENOWARN	Instructs the dialog box to perform no further action with the file name and not to warn the user of the situation.

OFN_SHAREWARN	This is the default response that is defined as 0. Instructs the dialog box to display a standard warning message.


See Also

TData struct

ShareViMsgId


TOpenSaveDialog::Response Table Entries

TOpenSaveDialog

The TOpenSaveDialog response table has no entries.


TOpenSaveDialog::TData struct

TOpenSaveDialog

Header File

opensave.h

Description

TOpenSaveDialog structure contains information about the user's file open or save selection. Specifically, this structure stores a user-specified file name filter, file extension, file name, the initial directory to use when displaying file names, any error codes, and various file attributes that determine, for example, if the file is a read-only file. The classes TFileOpenDialog and TFileSaveDialog use the information stored in this structure when a file is opened or saved.

Data Members

char* CustomFilter;

char* DefExt;

uint32 Error;

uint32 Flags;

char* FileName;

char* Filter;

int FilterIndex;

char* InitialDir;

Public Member Functions

void SetFilter(const char*filter = 0);


TOpenSaveDialog::TData::CustomFilter

TOpenSaveDialog::TData

Syntax

char* CustomFilter;

Description

CustomFilter stores the user-specified file filter; for example, *.CPP.


TOpenSaveDialog::TData::DefExt

TOpenSaveDialog::TData

Syntax

char* DefExt;

Description

DefExt stores the default extension.


TOpenSaveDialog::TData::Error

TOpenSaveDialog::TData

Syntax

uint32 Error;

Description

Error contains one or more of the following error codes:

Constant	Meaning

CDERR_DIALOGFAILURE	Failed to create a dialog box.

CDERR_LOCKRESOURCEFAILURE	Failed to lock a specified resource.

CDERR_LOADRESFAILURE	Failed to load a specified resource.

CDERR_LOADSTRFAILURE	Failed to load a specified string.


TOpenSaveDialog::TData::Flags

TOpenSaveDialog::TData

Syntax

uint32 Flags;

Description

Flag contains one or more of the following constants:

Constant	Meaning

OFN_HIDEREADONLY	Hides the read-only check box.

OFN_FILEMUSTEXIST	Lets the user enter only names of existing files in the File Name entry field. If an invalid file name is entered, a warning message is displayed.

OFN_PATHMUSTEXIST	Lets the user enter only valid path names. If an invalid path name is entered, a warning message is displayed.

OFN_NOVALIDATE	Performs no check of the file name and requires the owner of a derived class to perform validation.

OFN_NOCHANGEDIR	Sets the current directory back to what it was when the dialog was initiated.

OFN_ALLOWMULTISELECT	Allows multiple selections in the File Name list box.

OFN_CREATEPROMPT	Asks if the user wants to create a file that does not currently exist.

OFN_EXTENSIONDIFFERENT	Idicates the user entered a file name different from the specified in DefExt. This message is returned to the caller.

OFN_NOREADONLYRETURN	The returned file does not have the Read Only attribute set and is not in a write-protected directory. This message is returned to the caller.

OFN_NOTESTFILECREATE	The file is created after the dialog box is closed. If the application sets this flag, there is no check against write protection, a full disk, an open drive door, or network protection. For certain network environments, this flag should be set.

OFN_OVERWRITEPROMPT	The Save As dialog box displays a message asking the user if it's OK to overwrite an existing file.

OFN_SHAREAWARE	If this flag is set and a call to open a file fails because of a sharing violation, the error is ignored and the dialog box returns the given file name. If this flag is not set, the virtual function ShareViolation is called, which returns OFN_SHAREWARN (by default) or one of the following values:

OFN_SHAREFALLTHROUGH	File name is returned from the dialog box. OFN_SHARENOWARN No further action is taken.

OFN_SHAREWARN	User receives the standard warning message for this type of error.

OFN_SHOWHELP	Shows the Help button in the dialog box.


TOpenSaveDialog::TData::FileName

TOpenSaveDialog::TData

Syntax

char* FileName;

Description

Holds the name of the file to be saved or opened.


TOpenSaveDialog::TData::Filter

TOpenSaveDialog::TData

Syntax

char* Filter;

Description

Filter holds the filter to use initially when displaying file names.


TOpenSaveDialog::TData::FilterIndex

TOpenSaveDialog::TData

Syntax

int FilterIndex;

Description

FilterIndex indicates which filter to use initially when displaying file names.


TOpenSaveDialog::TData::InitialDir

TOpenSaveDialog::TData

Syntax

char* InitialDir;

Description

InitialDir holds the directory to use initially when displaying file names.


TOpenSaveDialog::TData Public Constructors and Destructor

See Also	TOpenSaveDialog::TData

Syntax

TData(uint32 flags=0, const char* filter=0, char* customFilter=0, char* initialDir=0, char* defExt=0);

Destructor

~TData();

Description

Constructs a TOpenSaveDialog::TData structure.

Destructor

Destructs a TOpenSaveDialog::TData structure.


See Also

TEditFile::FileData


TOpenSaveDialog::TData::SetFilter

TOpenSaveDialog::TData

Syntax

void SetFilter(const char*filter = 0);

Description

Makes a copy of the filter list used to display the file names.


TOutStream Class

OWL Hierarchy

Header File

docview.h

Description

Derived from TStream and ostream, TOutStream is a base class used to create output storage streams for a document.

Public Constructor

TOutStream(TDocument& doc, const char far* name, int mode);


TOutStream Public Constructor

See Also	TOutStream

Syntax

TOutStream(TDocument& doc, const char far* name, int mode);

Description

Constructs a TOutStream object. doc refers to the document object, name is the user-defined name of the stream, and mode is the mode of opening the stream.


See Also

TInStream

ofXXXX document open enum

shxxx document sharing enum


TPaintDC Class

OWL Hierarchy	Inheritance

Header File

dc.h

Description

A DC class derived from TWindowDC that wraps begin and end paint calls for use in a WM_PAINT response function.

Public Data Member

PAINTSTRUCT Ps;

Public Constructor and Destructor

TPaintDC(HWND wnd);

~TPaintDC();

Protected Data Member

HWND Wnd;


TPaintDC::Ps

See Also	TPaintDC

Syntax

PAINTSTRUCT Ps;

Description

The paint structure associated with this TPaintDC object.


See Also

PAINTSTRUCT struct


TPaintDC Public Constructor and Destructor

See Also	TPaintDC

Syntax

TPaintDC(HWND wnd);

Description

Creates a TPaintDC object with the given owned window. The data member Wnd is set to wnd.


See Also

TWindowDC::Wnd

TDC::TDC

Destructor

~TPaintDC();

Description

Destroys this object.


TPaintDC::Wnd

TPaintDC

Syntax

HWND Wnd

Description

The associated window handle.


TPalette::TPalette Class
TPalette Class

OWL Hierarchy	Inheritance

Header File

gdiobjec.h

Description

TPalette is the GDI Palette class derived from TGdiObject.  The TPalette constructors can create palettes from explicit information or indirectly from various color table types that are used by DIBs.

Public Constructors

TPalette(HPALETTE handle, TAutoDelete autoDelete = NoAutoDelete);

TPalette(const TClipboard&);

TPalette(const TPalette& palette);

TPalette(const LOGPALETTE far* logPalette);

TPalette(const PALETTEENTRY far* entries int count);

TPalette(const BITMAPINFO far* info, uint flags = 0);

TPalette(const BITMAPCOREINFO far* core, uint flags = 0);

TPalette(const TDib& dib, uint flags = 0);

TPalette();

Public Member Functions

void AnimatePalette(uint start, uint count, const PALETTEENTRY far* entries);

uint GetNearestPaletteIndex(TColor color) const;

uint GetNumEntries() const;

bool GetObject(uint16 far& numEntries) const;

uint GetPaletteEntries(uint16 start, uint16 count, PALETTEENTRY far* entries) const;

uint GetPaletteEntry(uint16 index, PALETTEENTRY far& entry) const;

TClipboard& operator << (TClipboard& clipboard, TPalette& palette);

operator HPALETTE() const;

bool ResizePalette(uint numEntries);

uint SetPaletteEntries(uint16 start, uint16 count, const PALETTEENTRY far* entries);

uint SetPaletteEntry(uint16 index, const PALETTEENTRY far& entry);

void ToClipboard(TClipboard& clipboard);

bool UnrealizeObject();

Protected Member Functions

void Create(const BITMAPINFO far* info, uint flags);

void Create(const BITMAPCOREINFO far* core, uint flags);


TPalette Public Constructors

See Also	TPalette

Syntax 1

TPalette(HPALETTE handle, TAutoDelete autoDelete = NoAutoDelete);

Description

Creates a TPalette object and sets the Handle data member to the given borrowed handle. The ShouldDelete data member defaults to false, ensuring that the borrowed handle will not be deleted when the C++ object is destroyed.

Syntax 2

TPalette(const TClipboard&);

Description

Creates a TPalette object with values taken from the given clipboard.

Syntax 3

TPalette(const TPalette& palette);

Description

This public copy constructor creates a complete copy of the given palette object as in

TPalette myPalette = yourPalette;

Syntax 4

TPalette(const LOGPALETTE far* logPalette);

Description

Creates a TPalette object from the given logPalette array.

Syntax 5

TPalette(const PALETTEENTRY far* entries, int count);

Description

Creates a TPalette object with count entries from the given entries array.

Syntax 6

TPalette(const BITMAPINFO far* info, uint flags = 0);

Description

Creates a TPalette object from the color table following the given BITMAPINFO structure. This constructor works only for 2-color, 16-color, and 256-color bitmaps. A handle with value 0 (zero) is returned for other bitmaps, including 24-bit DIBs.

Syntax 7

TPalette(const BITMAPCOREINFO far* core, uint flags = 0);

Description

For Presentation Manager (PM) 1.x DIBs only, creates a TPalette object from the color table following the given BITMAPCOREINFO structure. This constructor works only for 2-color, 16-color, and 256-color bitmaps. A handle with value 0 (zero) is returned for other bitmaps, including 24-bit DIBs. Note that every color in a PM 1.x table must be present because there is no ClrUsed field in the DIB header.

Syntax 8

TPalette(const TDib& dib, uint flags = 0);

Description

Creates a TPalette object from the given DIB object. The flags argument represents the values of the LOGPALETTE data structure used to create the palette.

Syntax 9

TPalette();

Description

For Presentation Manager only, creates a TPalette object that uses the default system palette.


See Also

TClipboard::GetClipboardData

TGdiObject::Handle

TGdiObject::ShouldDelete

TPalette::GetPaletteEntries

PALETTEENTRY struct


TPalette::AnimatePalette

TPalette

Syntax

void AnimatePalette(uint start, uint count, const PALETTEENTRY far* entries);

Description

Replaces entries in this logical palette from the entries array of PALETTEENTRY structures. The parameter start specifies the first entry to be animated, and count gives the number of entries to be animated. The new entries are mapped into the system palette immediately.


TPalette::GetNearestPaletteIndex

See Also	TPalette

Syntax

uint GetNearestPaletteIndex(TColor color) const;

Description

Returns the index of the color entry that represents the closest color in this palette to the given color.


See Also

TColor


TPalette::GetNumEntries

See Also	TPalette

Syntax

uint GetNumEntries() const;

Description

Returns the number of entries in this palette, or 0 if the call fails.


See Also

TGdiObject::GetObject


TPalette::GetObject

See Also	TPalette

Syntax

bool GetObject(uint16 far& numEntries) const;

Description

Finds the number of entries in this logical palette and sets the value in the numEntries argument. To find the entire LOGPALETTE structure, use GetPaletteEntries. Returns true if the call is successful; otherwise returns false.


See Also

TGdiObject::GetObject


TPalette::GetPaletteEntries

See Also	TPalette

Syntax

uint GetPaletteEntries(uint16 start, uint16 count,

                       PALETTEENTRY far* entries) const;

Description

Retrieves a range of entries in this logical palette and places them in the entries array. The start parameter specifies the first entry to be retrieved, and count gives the number of entries to be retrieved. Returns the number of entries actually retrieved, or 0 if the call fails.


See Also

PALETTEENTRY struct


TPalette::GetPaletteEntry

See Also	TPalette

Syntax

uint GetPaletteEntry(uint16 index, PALETTEENTRY far& entry) const;

Description

Retrieves the entry in this logical palette at index and places it in the entries array. Returns the number of entries actually retrieved: 1 if successful or 0 if the call fails.


See Also

TPalette::SetPaletteEntry

PALETTEENTRY struct


TPalette::operator <<

See Also	TPalette

Syntax

TClipboard& operator << (TClipboard& clipboard, TPalette& palette);

Description

Copies the given palette to the given clipboard argument. Returns a reference to the resulting clipboard, which allows normal chaining of <<.


See Also

TClipboard


TPalette::operator HPALETTE()

TPalette

Syntax

operator HPALETTE() const;

Description

Typecasting operator. Converts this palette's Handle to type HPALETTE, which is the data type representing the handle to a logical palette.


TPalette::ResizePalette

See Also	TPalette

Syntax

bool ResizePalette(uint numEntries);

Description

Changes the size of this logical palette to the number given by numEntries. Returns true if the call is successful; otherwise returns false.


See Also

TPalette::AnimatePalette


TPalette::SetPaletteEntries

TPalette

Syntax

uint SetPaletteEntries(uint16 start, uint16 count, const PALETTEENTRY far* entries);

Description

Sets the RGB color values in this palette from the entries array of PALETTEENTRY structures. The start parameter specifies the first entry to be animated, and count gives the number of entries to be animated. Returns the number of entries actually set, or 0 if the call fails.


TPalette::SetPaletteEntry

See Also	TPalette

Syntax

uint SetPaletteEntry(uint16 index, const PALETTEENTRY far& entry);

Description

Sets the RGB color value at index in this palette from the entry argument. The start parameter specifies the first entry to be animated, and count gives the number of entries to be animated. Returns 1, the number of entries actually set if successful, or 0 if the call fails.


See Also

PALETTEENTRY struct


TPalette::ToClipboard

See Also	TPalette

Syntax

void ToClipboard(TClipboard& clipboard);

Description

Moves this palette to the target clipboard argument. If a copy is to be put on the Clipboard, use TPalette(myPalette).ToClipboard; to make a copy first. The handle in the temporary copy of the object is moved to the clipboard. ToClipboard sets ShouldDelete to false so that the object on the clipboard is not deleted. The handle will still be available for examination.


See Also

TClipBoard::SetClipBoardData


TPalette::UnrealizeObject

See Also	TPalette

Syntax

bool UnrealizeObject();

Description

Directs the GDI to completely remap the logical palette to the system palette on the next RealizePalette(HDC) or TDC::RealizePalette call. Returns true if the call is successful; otherwise false.


See Also

TDC::RealizePalette


TPalette::Create

See Also	TPalette

Form 1

void Create(const BITMAPINFO far* info, uint flags);

Form 2

void Create(const BITMAPCOREINFO far* core, uint flags);

Description

Sets values in this palette from the given bitmap structure. These functions are usually called by the constructor rather than directly.


See Also

BITMAPCOREINFO struct

BITMAPINFO struct


TPaletteEntry Class

OWL Hierarchy

Header File

color.h

Description

TPaletteEntry is a support class derived from the structure tagPALETTEENTRY. The latter is defined as follows:

typedef struct tagPALETTEENTRY {

   uint8  peRed;

   uint8  peGreen;

   uint8  peBlue;

   uint8  peFlags;

} PALETTEENTRY;

The members peRed, peGreen, and peBlue specify the red, green, and blue intensity-values for a palette entry.

The peFlags member can be set to NULL or one of the following values:

Value	Meaning

PC_EXPLICIT	Specifies that the low-order word of the logical palette entry designates a hardware palette index. This flag allows the application to show the contents of the display device palette.

PC_NOCOLLAPSE	Specifies that the color be placed in an unused entry in the system palette instead of being matched to an existing color in the system palette. If there are no unused entries in the system palette, the color is matched normally. Once this color is in the system palette, colors in other logical palettes can be matched to this color.

PC_RESERVED	Specifies that the logical palette entry be used for palette animation; this prevents other windows from matching colors to this palette entry since the color frequently changes. If an unused system-palette entry is available, this color is placed in that entry. Otherwise, the color is available for animation.

TPaletteEntry is used in conjunction with the classes TPalette and TColor to simplify logical color-palette operations. Constructors are provided to create TPaletteEntry objects from explicit COLORREF and RGB values, or from TColor objects.

Public Constructors

TPaletteEntry(int r, int g, int b, int f = 0);

TPaletteEntry(TColor c);


TPaletteEntry Public constructors

See Also	TPaletteEntry

Syntax 1

TPaletteEntry(int r, int g, int b, int f = 0);

Description

Creates a palette entry object with peRed, peGreen, peBlue, and peFlags set to r, g, b, and f, respectively.

Syntax 2

TPaletteEntry(TColor c);

Description

Creates a palette entry object with peRed, peGreen, peBlue, and peFlags set to r, g, b, and f, respectively.


See Also

TColor::Red

TColor::Green

TColor::Blue


TPen Class

OWL Hierarchy	Inheritance

Header File

gdiobjec.h

Description

TPen is derived from TGdiObject. It encapsulates the GDI pen tool. Pens can be constructed from explicit information or indirectly. TPen relies on the base class's destructor, ~TGdiObject.

Public Constructors

TPen(HPEN handle, TAutoDelete autoDelete = NoAutoDelete);

TPen(TColor color, int width=1, int style=PS_SOLID);

TPen(const LOGPEN far* logPen);

TPen(const TPen& pen);

TPen(uint32 penStyle, uint32 width, const TBrush& brush, uint32 styleCount, uint32 style);

TPen(uint32 penStyle, uint32 width, const LOGBRUSH& logBrush, uint32 styleCount, uint32 style);

Public Member Functions

bool GetObject(LOGPEN far& logPen) const;

operator HPEN() const;


TPen Public Constructors

See Also	TPen

Form 1

TPen(HPEN handle, TAutoDelete autoDelete = NoAutoDelete);

Form 2

TPen(TColor color, int width=1, int style=PS_SOLID);

Form 3

TPen(const LOGPEN far* logPen);

Form 4

TPen(const Tpen& pen);

Form 5 (32-bit)

TPen(uint32 penStyle, uint32 width, const TBrush& brush, uint32 styleCount, uint32 style);

Form 6 (32-bit)

TPen(uint32 penStyle, uint32 width, const LOGBRUSH& logBrush, uint32 styleCount, uint32 style);

Description

Form 1: Creates a TPen object and sets the Handle data member to the given borrowed handle. The ShouldDelete data member defaults to false, ensuring that the borrowed handle will not be deleted when the C++ object is destroyed.

Form 2: Creates a TPen object with the given values. The width argument is in device units, but if set to 0, a 1-pixel width is assumed. Sets Handle with the given default values. If color is black or white, width is one, style is solid, a stock pen handle is returned. The values for style are listed in the following table.

Value	Meaning

PS_SOLID 	Creates a solid pen.

PS_DASH 	Creates a dashed pen. Valid only when the pen width is one or less in device units.

PS_DOT 	Creates a dotted pen. Valid only when the pen width is one or less in device units.

PS_DASHDOT	Creates a pen with alternating dashes dots. Valid only when the pen width is one or less in device units.

PS_DASHDOTDOT	Creates a pen with alternating dashes double-dots. Valid only when the pen width is one or less in device units.

PS_NULL 	Creates a null pen.

PS_INSIDEFRAME	Creates a solid pen. When this pen is used in any GDI drawing function that takes a bounding rectangle, the dimensions of the figure will be shrunk so that it fits entirely in the bounding rectangle, taking into account the width of the pen.

Form 3: Creates a TPen object from the given logPen values.

Form 4: The TPen copy constructor.

Form 5: (32-bit) Creates a TPen object with the given values.

Form 6: (32-bit) Creates a TPen object with the given values.


See Also

TColor

TGdiObject::Handle

TGdiObject::ShouldDelete

LOGBRUSH struct

LOGPEN struct


TPen::GetObject

See Also	TPen

Syntax

bool GetObject(LOGPEN far& logPen) const;

Description

Retrieves information about this pen object and places it in the given LOGPEN structure. Returns true if the call is successful, otherwise false.


See Also

TGdiObject::GetObject

LOGPEN struct


TPen::operator HPEN()

TPen

Syntax

operator HPEN() const;

Description

Typecasting operator. Converts this pen's Handle to type HPEN (the data type representing the handle to a logical pen).


TPicResult enum

OWL Hierarchy	See Also

Header File

validate.h

Syntax

enum TPicResult{prComplete, prIncomplete, prEmpty, prError, prSyntax, prAmbiguous, prIncompNoFill};

Description

TPicResult is the result type returned by the Picture member function of TPXPictureValidator. The result type indicates whether the data entered into the edit control matches a specified format. For example, prIncomplete indicates that the data entered is missing some information that was specified in the format picture of the data.


See Also

TPXPictureValidator::Picture


TPlacement enum

See Also	TPicResultenum

Header File

gadgetwi.h

Syntax

enum TPlacement {Before, After};

Description

Enumerates the placement of a gadget. The new gadget is inserted either before or after another gadget.

You can control the placement of the new gadget by specifying a sibling gadget that the new gadget is inserted before or after. If the sibling argument in TGadgetWindow::Insert is 0 then the new gadget is inserted at the beginning or the end of the existing gadgets. By default, the new gadget is inserted at the end of the existing gadgets.


See Also

TGadgetWindow::Insert


TPoint Class

OWL Hierarchy

Header File

geometry.h

Description

TPoint is a support class, derived from tagPOINT. The tagPOINT struct is defined as

struct tagPOINT {

   int x;

   int y;

};

TPoint encapsulates the notion of a two-dimensional point that usually represents a screen position. TPoint inherits two data members, the coordinates x and y, from tagPOINT. Member functions and operators are provided for comparing, assigning, and manipulating points. Overloaded << and >> operators allow chained insertion and extraction of TPoint objects with streams.

Public Constructors

TPoint();

TPoint(int _x, int _y);

TPoint(const POINT& point);

TPoint(const SIZE& size);

TPoint(uint32 dw);

Public Member Functions

TPoint& Offset(int dx, int dy);

TPoint OffsetBy(int dx, int dy) const;

TPoint operator +(const TSize& size) const;

TPoint operator -(const TSize& size) const;

TSize operator -(const TPoint& point) const;

TPoint operator -() const;

bool operator ==(const TPoint& other) const;

TPoint& operator +=(const TSize& size);

TPoint& operator -=(const TSize& size) const;

bool operator !=(const TPoint& other);

ipstream& operator >>(ipstream& is, TPoint& p);

istream& operator >>(istream& is, TPoint& p);

opstream& operator <<(opstream& os, const TPoint& p);

ostream& operator <<(ostream& os, const TPoint& p);


TPoint Public Constructors

See Also	TPoint

Syntax 1

TPoint();

Description

The default TPoint constructor.

Syntax 2

TPoint(int _x, int _y);

Description

Creates a TPoint object with the given coordinates.

Syntax 3

TPoint(const POINT& point);

Description

Creates a TPoint object with x = point.x,  y = point.y.

Syntax 4

TPoint(const SIZE& size);

Description

Creates a TPoint object with x = size.cx and y = size.cy.

Syntax 5

TPoint(uint32 dw);

Description

Creates a TPoint object with x = LOWORD(dw), y = HIWORD(dw)).


See Also

TSize


TPoint Offset
TPoint::Offset

See Also	TPoint

Syntax

TPoint& Offset(int dx, int dy);

Description

Offsets this point by the given delta arguments. This point is changed to (x + dx, y + dy). Returns a reference to this point.


See Also

TPoint::OffsetBy

TPoint::operator +=


TPoint::OffsetBy

See Also	TPoint

Syntax

TPoint OffsetBy(int dx, int dy) const;

Description

Calculates an offset to this point using the given displacement arguments. Returns the point (x + dx, y + dy). This point is not changed.


See Also

TPoint::operator +

TPoint::Offset


TPoint::operator +

See Also	TPoint

Syntax

TPoint operator +(const TSize& size) const;

Description

Calculates an offset to this point using the given size argument as the displacement. Returns the point (x + size.cx, y + size.cy). This point is not changed.


See Also

TPoint::OffsetBy

TSize


TPoint::operator -

See Also	TPoint

Syntax 1

TPoint operator -(const TSize& size) const;

Description

Calculates a negative offset to this point using the given size argument as the displacement. Returns the point (x - size.cx, y - size.cy). This point is not changed.

Syntax 2

TSize operator -(const TPoint& point) const;

Description

Calculates a distance from this point to the point argument. Returns the TSize object (x - point.x, y - point.y). This point is not changed.

Syntax 3

TPoint operator -() const;

Description

Returns the point (-x, -y). This point is not changed.


See Also

TPoint::operator +

TSize


TPoint::operator ==

See Also	TPoint

Syntax

bool operator ==(const TPoint& other) const;

Description

Returns true if this point is equal to the other point; otherwise returns false.


See Also

TPoint::operator !=


TPoint::operator +=

See Also	TPoint

Syntax

TPoint& operator +=(const TSize& size);

Description

Offsets this point by the given size argument. This point is changed to(x + size.cx, y + size.cy). Returns a reference to this point.


See Also

TPoint::Offset

TPoint::operator -=

TSize


TPoint::operator -=

See Also	TPoint

Syntax

TPoint& operator -=(const TSize& size);

Description

Negatively offsets this point by the given size argument. This point is changed to (x - size.cx, y - size.cy). Returns a reference to this point.


See Also

TPoint::Offset

TPoint::operator +=

TSize


TPoint::operator !=

See Also	TPoint

Syntax

bool operator !=(const TPoint& other) const;

Description

Returns false if this point is equal to the other point; otherwise returns true.


See Also

TPoint::operator ==


TPoint::operator >>

See Also	TPoint

Syntax 1

ipstream& operator >>(ipstream& is, TPoint& p);

Description

Extracts a TPoint object from persistent stream is, and copies it to p. Returns a reference to the resulting stream, allowing the usual chaining of << operations.

Syntax 2

istream& operator >>(istream& is, TPoint& p);

Description

Extracts a TPoint object from stream is, and copies it to p. Returns a reference to the resulting stream, allowing the usual chaining of >> operations.


See Also

TPoint operator <<


TPoint::operator <<

See Also	TPoint

Syntax 1

opstream& operator <<(opstream& os, const TPoint& p);

Description

Inserts the given TPoint object p into persistent stream os. Returns a reference to the resulting stream, allowing the usual chaining of >> operations.

Syntax 2

ostream& operator <<(ostream& os, const TPoint& p);

Description

Formats and inserts the given TPoint object p into the ostream os. The format is "(x,y)". Returns a reference to the resulting stream, allowing the usual chaining of << operations.


See Also

TPoint operator >>


TPointer<> Class

OWL Hierarchy

Header File

geometry.h

Description

A small utility class that provides automatic destruction for objects constructed using new. TPointer is a parameterized class that holds a pointer to its parameterized type and that overloads operators to behave like an object pointer. Assigning a pointer to a TPointer object eventually causes the object to be deleted when the function exits, when a TPointer goes out of scope, or when another pointer is assigned to the same object. A TPointer object can be instantiated using one of the following equivalent methods:

TPointer<SomeClass> p = new SomeClass;

TPointer<SomeClass> p(new SomeClass);

TPointer<SomeClass> p;    p = new SomeClass;

To remove the object, assign 0 to the pointer.

Public Constructors

TPointer() : TPointerBase<T>();

TPointer(T* pointer) : TPointerBase<T>(pointer);

Public Member Functions

T& operator *();

operator T*();

T* operator =(T* src);

T* operator =(const TPointer<T>& src);

T* operator ->();


TPointer Public Constructors

TPointer

Syntax 1

TPointer() : TPointerBase<T>();

Description

Default constructor in which a pointer p is initialized to 0.

Syntax 2

TPointer(T* pointer) : TPointerBase<T>(pointer);

Description

Initialized constructor in which a pointer p is initialized to pointer.


TPointer::operator *

TPointer

Syntax

T& operator *();

Description

Overloaded type conversion operator that casts its argument to a pointer to the passed in type.


TPointer::operator T*

TPointer

Syntax

operator T*();

Description

Overloaded type conversion operator that allows the TPointer object to be passed as a function argument or assigned to a variable as if it were a pointer.


TPointer::operator =

TPointer

Syntax 1

T* operator =(T* src);

Description

Assignment operator T* is assigned to a pointer p.

Syntax 2

T* operator =(const TPointer<T>& src);

Description

Assignment operator used when r is a const reference to TPointer of T. This operator saves converting if another pointer object is used.


TPointer::operator ->

TPointer

Syntax

T* operator ->();

Description

Provides access to the pointer.


TPopupMenu Class

OWL Hierarchy	Inheritance

Header File

menu.h

Description

TPopupMenu creates an empty pop-up menu to add to an existing window or pop-up menu.

Public Constructors

TPopupMenu(TAutoDelete autoDelete = AutoDelete);

TPopupMenu(HMENU handle, TAutoDelete autoDelete = NoAutoDelete);

Public Member Functions

bool TrackPopupMenu(uint flags, int x, int y, int rsvd, HWND wnd, TRect* rect = 0);

bool TrackPopupMenu(uint flags, TPoint& point, int rsvd, HWND wnd, TRect* rect = 0);


TPopupMenu Public Constructors

TPopupMenu

Form 1

TPopupMenu(TAutoDelete autoDelete = AutoDelete);

Form 2

TPopupMenu(HMENU handle, TAutoDelete autoDelete = NoAutoDelete);

Description

Form 1: Constructs an empty pop-up menu.

Description

Form 2: Alias constructor for a pop-up menu.


TPopupMenu::TrackPopupMenu

SeeAlsoTPopupMenu_TrackPopupMenuSeeAlso	TPopupMenu

Form 1

bool TrackPopupMenu(uint flags, int x, int y, int rsvd, HWND wnd, TRect* rect = 0);

Form 2

bool TrackPopupMenu(uint flags, TPoint& point, int rsvd, HWND wnd, TRect* rect = 0);

Description

Form 1: Allows the application to create a pop-up menu at the specified location in the specified window. flags specifies a screen position and can be one of the TPM_xxxx values(TPM_CENTERALIGN, TPM_LEFTALIGN, TPM_RIGHTALIGN, TPM_LEFTBUTTON, or TPM_RIGHTBUTTON). wnd is the handle to the window that receives messages about the menu.xspecifies the horizontal position in screen coordinates of the left side of the menu. y species the vertical position in screen coordinates of the top of the menu (for example, 0,0 specifies that a menu's left corner is in the top left corner of the screen). rect defines the area that the user can click without dismissing the menu.

Form 2: This function is the same as the previous TrackPopupMenu except that the x and y positions are specified in point.


See Also

TPM_ (Windows API)


TPreviewPage Class

OWL Hierarchy	Inheritance

Header File

preview.h

Description

TPreviewPage displays a page of a document in a print preview window. To obtain the information needed to display the page, TPreviewPage interacts with TPrintPreviewDC and TPrintout. Specifically, it creates a TPrintPreviewDC from the window DC provided in Paint and passes that TPrintPreviewDC object to TPrintout's SetPrintParams member function. The sample program PRINT.CPP displays the following print preview window:

Sample Print Preview Window

Public Constructor

TPreviewPage(TWindow* parent, TPrintout& printout, TPrintDC& prndc, TSize& printExtent, int pagenum = 1);

Public Member Functions

void Paint(TDC& dc, bool, TRect& clip);

void SetPageNumber(int newNum);

Protected Data Members

int PageNum;

TPrintDC& PrintDC;

TSize PrintExtent;

TPrintout& Printout;

Protected Member Functions

void EvSize(uint sizeType, TSize& size);

Response Table Entries

EV_ macros and member functions


Sample Print Preview Window


TPreviewPage Public Constructor

TPreviewPage

Constructor

TPreviewPage(TWindow* parent, TPrintout& printout, TPrintDC& prndc, TSize& printExtent, int pagenum = 1);

Description

Constructs a TPreviewPage object where parent is the parent window, printout is a reference to the corresponding TPrintout object, prndc is a reference to the TPrintPreviewDC object, printExtent is the extent (width and height) in logical units of the printed page, and pagenum is the number of the preview page. TPreviewPage has the attributes of a visible child window with a thin border. Sets the background color of the preview page window to white.


TPreviewPage::Paint

See Also	TPreviewPage

Syntax

void Paint(TDC& dc, bool, TRect& clip);

Description

Displays the page in the preview window. To determine the preview page's attributes (line width, and so on), Paint calls several of TPrintout's member functions. Then, to adjust the printer object for previewing, Paint determines if the page fits in the preview window or if clipping is necessary. Finally, Paint passes clipping and banding information to TPrintout's PrintPage function, which is called to display the page in the preview window.


See Also

TPrintout::BeginPrinting

TPrintout::EndPrinting

TPrintout::PrintPage


TPreviewPage::SetPageNumber

TPreviewPage

Syntax

void SetPageNumber(int newNum);

Description

Sets newNum to the number of the page currently displayed in the preview window.


TPreviewPage::PageNum

TPreviewPage

Syntax

int PageNum;

Description

Number of the page displayed in the preview window.


TPreviewPage::PrintDC

TPreviewPage

Syntax

TPrintDC& PrintDC;

Description

PrintDC& is a handle to the device context to use for printing.


TPreviewPage::PrintExtent

TPreviewPage

Syntax

TSize PrintExtent;

Description

Contains the extent (width and height) in logical units of the page.


TPreviewPage::Printout

TPreviewPage

Syntax

TPrintout& Printout;

Description

Holds a reference to the TPrintout object.


TPreviewPage::EvSize

TPreviewPage

Syntax

void EvSize(uint sizeType, TSize& size);

Description

Invalidates the entire window when the size of the page displayed in the preview window changes.


TPreviewPage::Response Table Entries

TPreviewPage

Response table entry	Member function

EV_WM_SIZE 	EvSize


TPrintDC Class

OWL Hierarchy	Inheritance

Header File

dc.h

Description

Derived from TDC, TPrintDC provides access to a printer.

Public Constructors

TPrintDC(HDC handle, TAutoDelete autoDelete = NoAutoDelete);

TPrintDC(const char far* driver, const char far* device, const char far* output, const DEVMODE far* initData);

Public Member Functions

int AbortDoc();

int BandInfo(TBandInfo& bandInfo);

static uint32 DeviceCapabilities(const char far* driver, const char far* device, const char far* port, int capability, char far* output=0, LPDEVMODE devmode=0);

int EndDoc();

int EndPage();

int Escape(int escape, int count=0, const void* inData=0, void* outData=0);

int NextBand(TRect& rect);

bool QueryAbort(int rsvd=0);

uint QueryEscSupport(int escapeNum);

int SetAbortProc(ABORTPROC proc);

int SetCopyCount(int reqestCount, int& actualCount);

int StartDoc(const char far* docName, const char far* output);

int StartPage();

Protected Data Member

DOCINFO DocInfo;


TPrintDC Public constructors

See Also	TPrintDC

Form 1

TPrintDC(HDC handle, TAutoDelete autoDelete = NoAutoDelete);

Form 2

TPrintDC(const char far* driver, const char far* device, const char far* output, const DEVMODE far* initData);

Description

Form 1: Creates a TPrint object for the DC given by handle.

Form 2: Creates a TPrint object given print driver, device, output, and data from the DEVMODE structure.


See Also

TDC

DEVMODE struct


TPrintDC AbortDoc
TPrintDC::AbortDoc

See Also	TPrintDC

Form 1

int AbortDoc();

Description

Aborts the current print job on this printer and erases everything drawn since the last call to StartDoc. AbortDoc calls the user-defined function set with TPrintDC::SetAbortProc to abort a print job because of error or user intervention. TPrintDC::EndDoc should be used to terminate a successfully completed print job.

If successful, AbortDoc returns a positive or zero value; otherwise a negative value is returned.


See Also

TPrintDC::EndDoc

TPrintDC::SetAbortProc

TPrintDC::Escape


TPrintDC::BandInfo

See Also	TPrintDC

Syntax

int BandInfo(TBandInfo& bandInfo);

Description

Retrieves information about the banding capabilities of this device, and copies it to the given bandInfo structure. Returns 1 if the call is successful; returns 0 if the call fails or if this device does not support banding.


See Also

TBandInfo

TPrintDC::Escape


TPrintDC::DeviceCapabilities

See Also	TPrintDC

Syntax

static uint32 DeviceCapabilities(const char far* driver, const char far* device, const char far* port, int capability, char far* output=0, LPDEVMODE devmode=0);

Description

Retrieves data about the specified capability of the named printer driver, device, and port, and places the results in the output char array. The driver, device, and port names must be zero-terminated strings. The devmode argument points to a DEVMODE struct. If devmode is 0 (the default), DeviceCapabilities retrieves the current default initialization values for the specified printer driver; otherwise, it retrieves the values contained in the DEVMODE structure. The format of the output array depends on the capability being queried. If output is 0 (the default), DeviceCapabilities returns the number of bytes required in the output array. Possible values for capability are as follows:

Value	Meaning

DC_BINNAMES	The function enumerates the paper bins on the given device. If a device driver supports this constant, the output array is a data structure that contains two members. The first member is an array identifying valid paper bins:

short BinList[cBinMax]

The second member is an array of character strings specifying the bin names:

char PaperNames[cBinMax][cchBinName]

If a device driver does not support this value, the output array is empty and the return value is NULL.

If output is NULL, the return value specifies the number of bins supported.

DC_BINS

The function retrieves a list of constants that identify the available bins and copies the list to the output array. If this array is NULL, the function returns the number of supported bins. The following bin identifiers can be returned:

DMBIN_AUTO

DMBIN_CASSETTE

DMBIN_ENVELOPE

DMBIN_ENVMANUAL

DMBIN_FIRST

DMBIN_LARGECAPACITY

DMBIN_LARGEFMT

DMBIN_LAST

DMBIN_LOWER

DMBIN_MANUAL

DMBIN_MIDDLE

DMBIN_ONLYONE

DMBIN_SMALLFMT

DMBIN_TRACTOR

DMBIN_UPPER

DC_DRIVER

The function returns the driver version number.

DC_DUPLEX

The function returns the level of duplex support. The return value is 1 if the function supports duplex output; otherwise it is 0.

DC_ENUMRESOLUTIONS

The function copies a list of available printer resolutions to the output array. The resolutions are copied as pairs of int32 integers; the first value of the pair specifies the horizontal resolution and the second value specifies the vertical resolution. If output is 0, the function returns the number of supported resolutions.

DC_EXTRA

The function returns the number of bytes required for the device-specific data that is appended to the DEVMODE structure.

DC_FIELDS

The function returns a value indicating which members of the DEVMODE structure are set by the device driver. This value can be one or more of the following constants:

DM_ORIENTATION

DM_PAPERSIZE

DM_PAPERLENGTH

DM_PAPERWIDTH

DM_SCALE

DM_COPIES

DM_DEFAULTSOURCE

DM_PRINTQUALITY

DM_COLOR

DM_DUPLEX

DM_YRESOLUTION

DM_TTOPTION

DC_FILEDEPENDENCIES

The function returns a list of files that must be loaded when the device driver is installed. If output is 0 and this value is specified, the function returns the number of file names that must be loaded. If output is nonzero, the function returns the specified number of 64-character file names.

DC_MAXEXTENT

The function returns the maximum supported paper-size. These dimensions are returned in a POINT structure; the x member gives the maximum paper width and the y member gives the maximum paper length.

DC_MINEXTENT

The function returns the minimum supported paper-size. These dimensions are returned in a POINT structure; the x member gives the minimum paper width and the y member gives the minimum paper length.

DC_ORIENTATION

This function returns the number of degrees that a portrait-oriented paper is rotated counterclockwise to produce landscape orientation. if the return value is 0, there is no landscape orientation. If the return value is 90, the portrait-oriented paper is rotated 90 degrees (as is the case when HP laser printers are used). if the return value is 270, the portrait-oriented paper is rotated 270 degrees (as is the case when dot-matrix printers are used).

DC_PAPERNAMES

This function returns a list of supported paper names such as Letter size or Legal size. The output array points to an array containing the paper names. If the output array is 0, the function returns the number of available paper sizes.

DC_PAPERS

The function retrieves a list of supported paper sizes and copies it to the output array. The function returns the number of sizes identified in the array. If output is 0, the function returns the number of supported paper sizes.

DC_PAPERSIZE

The function retrieves the supported paper sizes (specified in .1 millimeter units) and copies them to the output array.

DC_SIZE

The function returns the size of the DEVMODE structure required by the given device driver.

DC_TRUETYPE

This function returns the printer driver's TrueType font capabilities. The values returned can be one or more of the following constants:

DCTT_BITMAP	Device supports printing TrueType fonts as graphics.

(Dot-matrix and PCL printers)

DCTT_DOWNLOAD	Device supports downloading TryeType fonts.

(PostScript and PCL printers)

DCTT_SUBDEV	Device supports substituting device fonts for TrueType fonts.

(PostScript printers)

DC_VERSION

The function returns the device driver version number.

If DeviceCapabilities succeeds, the return value depends on the value of capability, as noted above. Otherwise, the return value is GDI_ERROR.


See Also

TDC::GetDeviceCaps

DEVMODE struct


TPrintDC::EndDoc

See Also	TPrintDC

Syntax

int EndDoc();

Description

Ends the current print job on this printer. EndDoc should be called immediately after a successfully completed print job. TPrintDC::AbortDoc should be used to terminate a print job because of error or user intervention.

If successful, EndDoc returns a positive or zero value; otherwise a negative value is returned.


See Also

TPrintDC::StartDoc

TPrintDC::AbortDoc

TPrintDC::Escape


TPrintDC::EndPage

See Also	TPrintDC

Syntax

int EndPage();

Description

Tells this printer's device driver that the application has finished writing to a page. If successful, EndPage returns a positive or zero value; otherwise a negative value is returned. Possible failure values are listed below:

Value	Meaning

SP_ERROR	General error.

SP_APPABORT	Job terminated because the application's print-canceling function returned 0.

SP_USERABORT	User terminated the job.

SP_OUTOFDISK	Insufficient disk space for spooling.

SP_OUTOFMEMORY	Insufficient memory for spooling.


See Also

TPrintDC::StartPage

TPrintDC::Escape


TPrintDC::Escape

TPrintDC

Syntax

int Escape(int escape, int count=0, const void* inData=0, void* outData=0);

Description

Allows applications to access the capabilities of a particular device that are not directly available through the GDI of this DC. The Escape call is specified by setting a mnemonic value in the escape argument. In Win32 the use of Escape with certain escape values has been replaced by specific functions. The names of these new functions are based on the corresponding escape mnemonic, as shown in the following table:

Value	Action

ABORTDOC	Superseded by TPrintDC_AbortDoc in Win32.

BANDINFO	Obsolete in Win32. Because all printer drivers for Windows version 3.1 and later set the text flag in every band, this escape is useful only for older printer drivers.

BEGIN_PATH	No changes for Win32. This escape is specific to PostScript printers.

CLIP_TO_PATH	No changes for Win32. This escape is specific to PostScript printers.

DEVICEDATA	Superseded in Win32. Applications should use the PASSTHROUGH escape to achieve the same functionality.

DRAFTMODE	Superseded in Win32. Applications can achieve the same functionality by setting the dmPrintQuality member of the DEVMODE structure to DMRES_DRAFT and passing this structure to the CreateDC function.

DRAWPATTERNRECT	No changes for Win32.

ENABLEDUPLEX	Superseded in Win32. Applications can achieve the same functionality by setting the dmDuplex member of the DEVMODE structure and passing this structure to the CreateDC function.

ENABLEPAIRKERNING	No changes for Win32.

ENABLERELATIVEWIDTHS	No changes for Win32.

ENDDOC	Superseded by TPrintDC_EndDoc in Win32.

END_PATH	No changes for Win32. This escape is specific to PostScript printers.

ENUMPAPERBINS	Superseded in Win32. Applications can use TPrintDC::DeviceCapabilities to achieve the same functionality.

ENUMPAPERMETRICS	Superseded in Win32. Applications can use TPrintDC::DeviceCapabilities to achieve the same functionality.

EPSPRINTING	No changes for Win32. This escape is specific to PostScript printers.

EXT_DEVICE_CAPS	Superseded in Win32. Applications can use TDC::GetDeviceCaps to achieve the same functionality. This escape is specific to PostScript printers.

EXTTEXTOUT	Superseded in Win32. Applications can use TDC::ExtTextOut to achieve the same functionality. This escape is not supported by the version 3.1 PCL driver.

FLUSHOUTPUT	Removed for Win32.

GETCOLORTABLE	Removed for Win32.

GETEXTENDEDTEXTMETRICS	No changes for Win32. Support for this escape might change in future versions of Windows.

GETEXTENTTABLE	Superseded in Win32. Applications can use ::GetCharWidth to achieve the same functionality. This escape is not supported by the version 3.1 PCL or PostScript drivers.

GETFACENAME	No changes for Win32. This escape is specific to PostScript printers.

GETPAIRKERNTABLE	No changes for Win32.

GETPHYSPAGESIZE	No changes for Win32. Support for this escape might change in future versions of Windows.

GETPRINTINGOFFSET	No changes for Win32. Support for this escape might change in future versions of Windows.

GETSCALINGFACTOR	No changes for Win32. Support for this escape might change in future versions of Windows.

GETSETPAPERBINS	Superseded in Win32. Applications can achieve the same functionality by calling TPrintDC::DeviceCapabilities to find the number of paper bins, calling ::ExtDeviceMode to find the current bin, and then setting the dmDefaultSource member of the DEVMODE structure and passing this structure to the CreateDC function. GETSETPAPERBINS changes the paper bin only for the current device context. A new device context will use the system-default paper bin until the bin is explicitly changed for that device context.

GETSETPAPERMETRICS	Obsolete in Win32. Applications can use TPrintDC::DeviceCapabilities and ::ExtDeviceMode to achieve the same functionality.

GETSETPAPERORIENT	Obsolete in Win32. Applications can achieve the same functionality by setting the dmOrientation member of the DEVMODE structure and passing this structure to the CreateDC function. This escape is not supported by the Windows 3.1 PCL driver.

GETSETSCREENPARAMS	No changes for Win32.

GETTECHNOLOGY	No changes for Win32. Support for this escape might change in future versions of Windows. This escape is not supported by the Windows 3.1 PCL driver.

GETTRACKKERNTABLE	No changes for Win32.

GETVECTORBRUSHSIZE	No changes for Win32. Support for this escape might change in future versions of Windows.

GETVECTORPENSIZE	No changes for Win32. Support for this escape might change in future versions of Windows.

MFCOMMENT	No changes for Win32.

NEWFRAME	No changes for Win32. Applications should use ::StartPage and ::EndPage instead of this escape. Support for this escape might change in future versions of Windows.

NEXTBAND	No changes for Win32. Support for this escape might change in future versions of Windows.

PASSTHROUGH	No changes for Win32.

QUERYESCAPESUPPORT	No changes for Win32.

RESTORE_CTM	No changes for Win32. This escape is specific to PostScript printers.

SAVE_CTM	No changes for Win32. This escape is specific to PostScript printers.

SELECTPAPERSOURCE	Obsolete in Win32. Applications can achieve the same functionality by using TPrintDC::DeviceCapabilities.

SETABORTPROC	Superseded in Win32 by ::SetAbortProc. See TPrintDC::SetAbortProc.

SETALLJUSTVALUES	No changes for Win32. Support for this escape might change in future versions of Windows. This escape is not supported by the Windows 3.1 PCL driver.

SET_ARC_DIRECTION	No changes for Win32. This escape is specific to PostScript printers.

SET_BACKGROUND_COLOR	No changes for Win32. Applications should use ::SetBkColor instead of this escape. Support for this escape might change in future versions of Windows.

SET_BOUNDS	No changes for Win32. This escape is specific to PostScript printers.

SETCOLORTABLE	No changes for Win32. Support for this escape might change in future versions of Windows.

SETCOPYCOUNT	Superseded in Win32. An application should call TPrintDC::DeviceCapabilities, specifying DC_COPIES for the capability parameter, to find the maximum number of copies the device can make. Then the application can set the number of copies by passing to the CreateDC function a pointer to the DEVMODE structure.

SETKERNTRACK	No changes for Win32.

SETLINECAP	No changes for Win32. This escape is specific to PostScript printers.

SETLINEJOIN	No changes for Win32. This escape is specific to PostScript printers.

SETMITERLIMIT	No changes for Win32. This escape is specific to PostScript printers.

SET_POLY_MODE	No changes for Win32. This escape is specific to PostScript printers.

SET_SCREEN_ANGLE	No changes for Win32.

SET_SPREAD	No changes for Win32.

STARTDOC	Superseded in Win32. Applications should call ::StartDoc instead of this escape.

TRANSFORM_CTM	No changes for Win32. This escape is specific to PostScript printers.

Escape calls are translated and sent to the printer device driver. The inData buffer lets you supply any data needed for the escape. You must set count to the size (in bytes) of the inData buffer. If no input data is required, inData and count should be set to the default value of 0. Similarly, you must supply an outData buffer for those Escape calls that retrieve data. If the escape does not supply output, set outData to the default value of 0.


TPrintDC::NextBand

See Also	TPrintDC

Syntax

int NextBand(TRect& rect);

Description

Tells this printer's device driver that the application has finished writing to a band. The device driver sends the completed band to the Print Manager and copies the coordinates of the next band in the rectangle specified by rect.

If successful, NextBand returns a positive or zero value; otherwise a negative value is returned. Possible failure values are listed below:

Value	Meaning

SP_ERROR	General error.

SP_APPABORT	Job terminated because the application's print-canceling function returned 0.

SP_USERABORT	User terminated the job.

SP_OUTOFDISK	Insufficient disk space for spooling.

SP_OUTOFMEMORY	Insufficient memory for spooling.


See Also

TPrintDC::Escape

TPrintDC::BandInfo


TPrintDC::QueryAbort

See Also	TPrintDC

Syntax

bool QueryAbort(int rsvd=0);

Description

16-bit applications only. Tries to call the AbortProc callback function for this printer to determine if a print job should be aborted or not. QueryAbort returns the value returned by AbortProc or true if no such callback function exists. true indicates that printing should continue; false indicates that the print job should be terminated. The rsvd argument is a reserved value that should be set to 0.


See Also

TPrintDC::SetAbortProc

TPrintDC::AbortDoc


TPrintDC::QueryEscSupport

See Also	TPrintDC

Syntax

uint QueryEscSupport(int escapeNum);

Description

Returns true if the escape specified by escapeNum is implemented on this device; otherwise false.


See Also

TPrintDC::Escape


TPrintDC::SetAbortProc

See Also	TPrintDC

Syntax

int SetAbortProc(ABORTPROC proc);

Description

Establishes the user-defined proc as the printer-abort function for this printer. This function is called by TPrintDC::AbortDoc to cancel a print job during spooling.

SetAbortProc returns a positive (nonzero) value if successful; otherwise it returns a negative (nonzero) value.


See Also

TPrintDC::Escape


TPrintDC::SetCopyCount

See Also	TPrintDC

Syntax

int SetCopyCount(int reqestCount, int& actualCount);

Description

Sets requestCount to the number of uncollated copies of each page that this printer should print. The actual number of copies to be printed is copied to actualCount. The actual count will be less than the requested count if the latter exceeds the maximum allowed for this device. SetCopyCount returns 1 if successful; otherwise, it returns 0.


See Also

TPrintDC::DeviceCapabilities

TPrintDC::Escape


TPrintDC::StartDoc

See Also	TPrintDC

Syntax

int StartDoc(const char far* docName, const char far* output);

Description

Starts a print job for the named document on this printer DC. If successful, StartDoc returns a positive value, the job ID for the document. If the call fails, the value SP_ERROR is returned. Detailed error information can be obtained by calling GetLastError.

This function replaces the earlier ::Escape call with value STARTDOC.


See Also

TPrintDC::EndDoc

TPrintDC::Escape


TPrintDC::StartPage

See Also	TPrintDC

Syntax

int StartPage();

Description

Prepares this device to accept data. The system disables ::ResetDC between calls to StartPage and EndPage, so that applications cannot change the device mode except at page boundaries. If successful, StartPage returns a positive value; otherwise, a negative or zero value is returned.


See Also

TPrintDC::EndPage


TPrintDC::DocInfo

See Also	TPrintDC

Syntax

DOCINFO DocInfo;

Description

Holds the input and output file names used by TPrintDC::StartDoc. The DOCINFO structure is defined as follows:

typedef struct {

   int cbSize;          // size of the structure, bytes

   DocInfo lpszDocName;   // document name <= 32 chars inc. final 0

   DocInfo lpszOutput;    // output file name

} DOCINFO;

The lpszOutput field allows a print job to be redirected to a file. If this field is NULL, the output will go to the device for the specified DC.


See Also

TPrintDC::StartDoc


TPrintDialog::TData struct

See Also	OWL Hierarchy

Header File

printdia.h

Description

TPrintDialog::TData contains information required to initialize the printer dialog box with the user's print selections. This information consists of the number of copies to be printed, the first and last pages to print, the maximum and minimum number of pages that can be printed and various flag values that indicate whether the Pages radio button is displayed, the Print to File check box is enabled, and so on.TPrintDialog uses this struct to initialize the print dialog box. Whenever the user changes the print requirements, this struct is updated.

If an error occurs, TPrintDialog::TData returns one of the common dialog extended error codes. TPrintDialog::TData also takes care of locking and unlocking memory associated with the DEVMODE and DEVNAMES structures, which contain information about the printer driver, the printer, and the output printer port.

TPrinter has access to this information through its data member, Data

Public data members

int Copies;

uint32 Error;

uint32 Flags;

int FromPage;

int MaxPage;

int MinPage;

int ToPage;

Public member functions

void ClearDevMode();

void ClearDevNames();

const char far* GetDeviceName() const;

const DEVMODE far* GetDevMode() const;

const DEVNAMES far* GetDevNames() const;

const char far* GetDriverName() const;

const char far* GetOutputName() const;

void Lock();

void SetDevMode(const DEVMODE far* devMode);

void SetDevNames(const char far* driver, const char far* device, const char far* output);

TPrintDC* TransferDC();

void Unlock();


See Also

TPrintDialog

TPrinter


TPrintDialog::TData::Copies

TPrintDialog::TData struct

Syntax

int Copies;

Description

Copies indicates the actual number of pages to be printed.


TPrintDialog::TData::Error

TPrintDialog::TData struct

Syntax

uint32 Error;

Description

 If the dialog box is successfully executed, Error returns 0. Otherwise, it contains one of the following error codes.

Constant	Meaning

CDERR_DIALOGFAILURE	Failed to create a dialog box.

CDERR_FINDRESFAILURE	Failed to find a specified resource.

CDERR_INITIALIZATION	Failed to initialize the common dialog box function.

A lack of sufficient memory can generate this error.

CDERR_LOCKRESOURCEFAILURE	Failed to lock a specified resource.

CDERR_LOADRESFAILURE	Failed to load a specified resource.

CDERR_LOADSTRFAILURE	Failed to load a specified string.

CDERR_MEMALLOCFAILURE	Unable to allocate memory for internal data structures.

CDERR_MEMLOCKFAILURE	Unable to lock the memory associated with a handle.

CDERR_REGISTERMSGFAIL	A message, designed for the purpose of communicating between two applications, could not be registered.

PDERR_CREATEICFAILURE	TPrintDialog failed to create an information context.

PDERR_DEFAULTDIFFERENT	The printer described by structure members doesn't match the default printer. This error message can occur if the user changes the printer specified in the control panel.

PDERR_DNDMMISMATCH	The printer specified in DevMode and in DevNames is different.

PDERR_GETDEVMODEFAIL	The printer device-driver failed to initialize the DevMode structure.

PDERR_INITFAILURE 	The TPrintDialog structure could not be initialized.

PDERR_LOADDRVFAILURE	The specified printer's device driver could not be loaded.

PDERR_NODEFAULTPRN	A default printer could not be identified.

PDERR_NODEVICES	No printer drivers exist.

PDERR_PARSEFAILURE	The string in the [devices] section of the WIN.INI file could not be parsed.

PDERR_PRINTERNOTFOUND	The [devices] section of the WIN.INI file doesn't contain the specified printer.

PDERR_RETDEFFAILURE	Either DevMode or DevNames contain zero.

PDERR_SETUPFAILURE	TPrintDialog failed to load the required resources.


TPrintDialog::TData::Flags

TPrintDialog::TData struct

Syntax

uint32 Flags;

Description

Flags , which are used to initialize the printer dialog box, can be one or more of the following values that control the appearance and functionality of the dialog box:

Constant	Meaning

PD_ALLPAGES 	Indicates that the All radio button was selected when the user closed the dialog box.

PD_COLLATE 	Causes the Collate checkbox to be checked when the dialog box is created.

PD_DISABLEPRINTTOFILE	Disables the Print to File check box.

PD_HIDEPRINTTOFILE	Hides and disables the Print to File check box.

PD_NOPAGENUMS 	Disables the Pages radio button and the associated edit control.

PD_NOSELECTION	Disables the Selection radio button.

PD_NOWARNING 	Prevents the warning message from being displayed when there is no default printer.

PD_PAGENUMS 	Selects the Pages radio button when the

dialog box is created.

PD_PRINTSETUP 	Displays the Print Setup dialog box rather than the Print dialog box.

PD_PRINTTOFILE	Checks the Print to File check box when the dialog box is created.

PD_RETURNDC 	Returns a device context matching the selections that the user made in the dialog box.

PD_RETURNDEFAULT	Returns DevNames structures that are initialized for the default printer without displaying a dialog box.

PD_RETURNIC 	Returns an information context matching the selections that the user made in the dialog box.

PD_SELECTION 	Selects the Selection radio button when the dialog box is created.

PD_SHOWHELP 	Shows the Help button in the dialog box.

PD_USEDEVMODECOPIES	If a printer driver supports multiple copies, setting this flag causes the requested number of copies to be stored in the dmCopies member of the DevMode structure and 1 in Copies. If a printer driver does not support multiple copies, setting this flag disables the Copies edit control. If this flag is not set, the number 1 is stored in DevMode and the requested number of copies in Copies.


TPrintDialog::TData::FromPage

See AlsoTPrintDialog::TData struct

Syntax

int FromPage;

Description

FromPage indicates the beginning page to print.


See Also

TPrintDialog::TData::ToPage


TPrintDialog::TData::MaxPage

TPrintDialog::TData struct

Syntax

int MaxPage;

Description

MaxPage indicates the maximum number of pages that can be printed.


TPrintDialog::TData::MinPage

TPrintDialog::TData struct

Syntax

int MinPage;

Description

MinPage indicates the minimum number of pages that can be printed.


TPrintDialog::TData::ToPage

See Also	TPrintDialog

Syntax

int ToPage;

Description

ToPage indicates the ending page to print.


See Also

TPrintDialog::TData::FromPage


TPrintDialog::TData::ClearDevMode

TPrintDialog::TData struct

Syntax

void ClearDevMode();

Description

Clears device mode information (information necessary to initialize the dialog controls).


TPrintDialog::TData::ClearDevNames

TPrintDialog::TData struct

Syntax

void ClearDevNames();

Description

Clears the device name information (information that contains three strings used to specify the driver name, the printer name, and the output port name).


TPrintDialog::TData::GetDeviceName

TPrintDialog::TData struct

Syntax

const char far* GetDeviceName() const;

Description

Gets the name of the output device.


TPrintDialog::TData::GetDevMode

TPrintDialog::TData struct

Syntax

const DEVMODE far* GetDevMode() const;

Description

Gets a pointer to a DEVMODE structure (a structure containing information necessary to initialize the dialog controls).


TPrintDialog::TData::GetDevNames

TPrintDialog::TData struct

Syntax

const DEVNAMES far* GetDevNames() const;

Description

Gets a pointer to a DEVNAMES structure (a structure containing three strings used to specify the driver name, the printer name, and the output port name).


TPrintDialog::TData::GetDriverName

TPrintDialog::TData struct

Syntax

const char far* GetDriverName() const;

Description

Gets the name of the printer device driver.


TPrintDialog::TData::GetOutputName

TPrintDialog::TData struct

Syntax

const char far* GetOutputName() const;

Description

Gets the name of the physical output medium.


TPrintDialog::TData::Lock

TPrintDialog::TData struct

Syntax

void Lock();

Description

Locks memory associated with the DEVMODE and DEVNAMES structures.


TPrintDialog::TData::SetDevMode

TPrintDialog::TData struct

Syntax

void SetDevMode(const DEVMODE far* devMode);

Description

Sets the values for the DEVMODE structure.


TPrintDialog::TData::SetDevNames

TPrintDialog::TData struct

Syntax

void SetDevNames(const char far* driver, const char far* device, const char far* output);

Description

Sets the values for the DEVNAMES structure.


TPrintDialog::TData::TransferDC

TPrintDialog::TData struct

Syntax

TPrintDC* TransferDC();

Description

Creates and returns a TPrintDC with the current settings.


TPrintDialog::TData::Unlock

TPrintDialog

Syntax

void Unlock();

Description

Unlocks memory associated with the DEVMODE and DEVNAMES structures.


TPrintDialog class

OWL Hierarchy	Inheritance

Header File

printdia.h

Description

TPrintDialog displays either a modal print or a print setup dialog box. The print dialog box lets you specify the characteristics of a particular print job. The setup dialog box lets you configure the printer and specify additional print job characteristics. You can also use TPrinter and TPrintout to provide support for printer dialog boxes.  TPrintDialog uses the TPrintDialog::TData structure to initialize the dialog box with the user's printer options, such as the number of pages to print, the output device, and so on.

Public Constructor

TPrintDialog(TWindow* parent, TData& data, const char far* printTemplateName=0, const char far* setupTemplateName=0, const char far* title=0, TModule* module=0);

Public Member Functions

int DoExecute();

bool GetDefaultPrinter();

Protected Data Members

TData& Data;

PRINTDLG pd;

Protected Member Functions

void CmSetup();

bool DialogFunction(uint message, WPARAM, LPARAM);

Response Table Entries

The TPrintDialog Response Table has no entries.


TPrintDialog Public Constructor

TPrintDialog

Syntax

TPrintDialog(TWindow* parent, TData& data, const char far* printTemplateName=0, const char far* setupTemplateName=0, const char far* title=0, TModule* module=0);

Description

Constructs a print or print setup dialog box with specified data from the TPrintDialog::TData struct structure, parent window, window caption, print and setup templates, and module.


TPrintDialog::DoExecute

TPrintDialog

Syntax

int DoExecute();

Description

If no error occurs, DoExecute copies flags and print specifications into the data argument in the constructor. If an error occurs, DoExecute sets the error number of data to an error code from TPrintDialog::TData::Error.


TPrintDialog::GetDefaultPrinter

TPrintDialog

Syntax

bool GetDefaultPrinter();

Description

Without displaying a dialog box, GetDefaultPrinter gets the device mode and name that are initialized for the system default printer.


TPrintDialog::Data

See Also	TPrintDialog

Syntax

TData& Data;

Description

Data is a reference to the TData object passed in the constructor. The TData object contains print specifications such as the number of copies to be printed, the number of pages, the output device name, and so on.


See Also

TPrintDialog::TData struct


TPrintDialog::pd

See Also	TPrintDialog

Syntax

PRINTDLG pd;

Description

Specifies the dialog box print job characteristics such as page range, number of copies, device context, and so on necessary to initialize the print or print setup dialog box.


See Also

TPrintDialog::TData struct


TPrintDialog::CmSetup

TPrintDialog

Syntax

void CmSetup();

Description

Responds to the click of the setup button with an EV_COMMAND message.


TPrintDialog::DialogFunction

See Also	TPrintDialog

Syntax

bool DialogFunction(uint message, WPARAM, LPARAM);

Description

Returns true if a message is handled.


See Also

TDialog::DialogFunction


TPrintDialog Response Table Entries

TPrintDialog

Description

The TPrintDialog response table has no entries.


 TPrinter Class

OWL Hierarchy	Inheritance

Header File

printer.h

Description

TPrinter represents the physical printer device. To print or configure a printer, initialize an instance of TPrinter.

Public Constructor and Destructor

TPrinter();

virtual ~TPrinter();

Public Member Functions

virtual void ClearDevice();

TPrintDialog::TData& GetSetup();

static bool GetUserAbort();

virtual bool Print(TWindow* parent, TPrintout& printout, bool prompt);

virtual void ReportError(TWindow* parent, TPrintout& printout);

virtual void Setup(TWindow* parent);

static void SetUserAbort(bool abort = true);

Protected Data Members

TPrintDialog::TData* Data;

int Error;

bool UseBandInfo;

unsigned Flags;

bool FirstBand;

TRect BandRect;

TSize PageSize;

Protected Member Functions

virtual TWindow* CreateAbortWindow(TWindow* parent, TPrintout& printout);

virtual bool ExecPrintDialog(TWindow* parent);

virtual void GetDefaultPrinter();

virtual void SetPrinter(const char* driver, const char* device, const char* output);

void CalcBandingFlags(TPrintDC& prnDC);


TPrinter Public Constructor and Destructor

TPrinter

Syntax

TPrinter();

Destructor

virtual ~TPrinter();

Description

Constructs an instance of TPrinter associated with the default printer. To change the printer, call SetDevice after the object has been initialized or call Setup to let the user select the new device through a dialog box.

Destructor

Frees the resources allocated to TPrinter.


TPrinter::ClearDevice

TPrinter

Syntax

virtual void ClearDevice();

Description

Called by SetPrinter and the Destructor, ClearDevice disassociates the device with the current printer. ClearDevice changes the current status of the printer to PF_UNASSOCIATED, which causes the object to ignore all calls to Print until the object is reassociated with a printer.


TPrinter::Print

See Also	TPrinter

Syntax

virtual bool Print(TWindow* parent, TPrintout& printout, bool prompt);

Description

Print renders the given printout object on the associated printer device and displays an Abort dialog box while printing. It displays any errors encountered during printing. Prompt allows you to show the user a window.


See Also

TPrinter::Error


TPrinter::ReportError

TPrinter

Syntax

virtual void ReportError(TWindow* parent, TPrintout& printout);

Description

Print calls ReportError if it encounters an error. By default, it brings up the system message box with an error string created from the default string table. This function can be overridden to show a custom error dialog box.


TPrinter::Setup

TPrinter

Syntax

virtual void Setup(TWindow* parent);

Description

Setup lets the user select and/or configure the currently associated printer. Setup  opens a dialog box as a child of the given window. The user then selects one of the buttons in the dialog box to select or configure the printer. The form of the dialog box is based on  TPrintDialog, the common dialog printer class.


TPrinter::GetSetup

TPrinter

Syntax

TPrintDialog::TData& GetSetup();

Description

Returns a reference to the TPrintDialog data structure.


TPrinter::SetUserAbort

TPrinter

Syntax

static void SetUserAbort(bool abort=true);

Description

Sets the printing abort flag.


TPrinter::GetUserAbort

TPrinter

Syntax

static bool GetUserAbort();

Description

Returns true if the user has chosen to stop printing through the printing dialog. Returns false otherwise.


TPrinter::Data

See Also	TPrinter

Syntax

TPrintDialog::TData* Data;

Description

Data is a pointer to the TPrintDialog data structure that contains information about the user's print selection.


See Also

TPrintDialog::TData struct


TPrinter::Error

TPrinter

Syntax

int Error;

Description

Error is the error code returned by GDI during printing. This value is initialized during a call to Print.


TPrinter::UseBandInfo

TPrinter

Syntax

bool UseBandInfo;

Description

UseBandInfo is set to true if the printer supports banding, otherwise it's set to false.


TPrinter::Flags

TPrinter

Syntax

unsigned Flags;

Description

The Flags data member specifies whether the printout bands contain graphics bands, text bands, or both. The valid flag values are enumerated by TPrintoutFlags:

enum TPrintoutFlags {

   pfGraphics // Current band accepts graphics

   pfText     // Current band accepts text

   pfBoth     // Current band accepts either graphics or text

};


TPrinter::FirstBand

TPrinter

Syntax

bool FirstBand;

Description

FirstBand is set to true if the first band of the print job is being printed, otherwise false.


TPrinter::BandRect

TPrinter

Syntax

TRect BandRect;

Description

BandRect specifies the size of the banding rectangle.


TPrinter::PageSize

TPrinter

Syntax

TSize PageSize;

Description

PageSize specifies the size of the printed page, as specifed in the device context.


TPrinter::CreateAbortWindow

TPrinter

Syntax

virtual TWindow* CreateAbortWindow(TWindow* parent, TPrintout& printout);

Description

Creates a printer abort dialog message box.


TPrinter::ExecPrintDialog

TPrinter

Syntax

virtual bool ExecPrintDialog(TWindow* parent);

Description

Executes a TPrintDialog.


TPrinter::GetDefaultPrinter

TPrinter

Syntax

virtual void GetDefaultPrinter();

Description

Updates the printer structure with information about the user's default printer.


TPrinter::SetPrinter

TPrinter

Syntax

virtual void SetPrinter(const char* driver, const char* device, const char* output);

Description

SetPrinter changes the printer device association. Setup calls SetPrinter to change the association interactively. The valid parameters to this method can be found in the [devices] section of the WIN.INI file.

Entries in the [devices] section have the following format:

<device name>=<driver>, <port> {, <port>}


TPrinter::CalcBandingFlags

TPrinter

Syntax

void CalcBandingFlags(TPrintDC& prnDC);

Description

CalcBandingFlags determines if there are either text and graphics bands, and sets data member Flags  accordingly.


TPrinter::TXPrinter class

TPrinter	OWL Hierarchy	Inheritance

Header File

printer.h

Description

A nested class, TXPrinter describes an exception that results from an invalid printer object. This type of error can occur when printing to the physical printer.

Public constructors

TXPrinter(uint resId = IDS_PRINTERERROR);


TPrinter::TXPrinter Public Constructors

TPrinter::TXPrinter

Syntax

TXPrinter(uint resId = IDS_PRINTERERROR);

Description

Constructs a TXPrinter object with a default IDS_PRINTERERROR message.


 TPrinterAbortDlg class

OWL Hierarchy	Inheritance

Header File

printer.h

Description

TPrinterAbortDlg is the object type of the default printer-abort dialog box. This dialog box is initialized to display the title of the current printout, as well as the device and port currently used for printing.

TPrinterAbortDlg expects to have three static text controls, with control IDs of 101 for the title, 102 for the device, and 103 for the port. These controls must have "%s" somewhere in the text strings so that they can be replaced by the title, device, and port. The dialog-box controls can be in any position and tab order.

Public Constructor

TPrinterAbortDlg(TWindow* parent, TResId resId, const char far* title, const char far* device, const char far* port);

Protected Member Functions

virtual LRESULT EvCommand(uint id, HWND hWndCtl, uint notifyCode);

void SetupWindow();


TPrinterAbortDlg Public Constructors
TPrinterAbortDlg Public Constructor

TPrinterAbortDlg

Constructor

TPrinterAbortDlg(TWindow* parent, TResId resId, const char far* title, const char far* device, const char far* port);

Description

Constructs an Abort dialog box that contains a Cancel button and displays the given title, device, and port.


TPrinterAbortDlg EvCommand
TPrinterAbortDlg::EvCommand

TPrinterAbortDlg

Syntax

virtual LRESULT EvCommand(uint id, HWND hWndCtl, uint notifyCode);

Description

Handles the Cancel button on the Printer-abort dialog box.


TPrinterAbortDlg::SetupWindow

See Also	TPrinterAbortDlg

Syntax

void SetupWindow();

Description

Associates objects with the dialog resource template so that the title, device, and port can be determined for printing. See the description of TPrintoutFlags for information about printing flags and printer status information.


See Also

TPrintoutFlagsenum


TPrintout Class

OWL Hierarchy	Inheritance

Header File

printer.h

Description

TPrintout represents the physical printed document that is to sent to a printer to be printed. TPrintout does the rendering of the document onto the printer. Because this object type is abstract, it cannot be used to print anything by itself. For every document, or document type, a class derived from TPrintout must be created and its PrintPage function must be overridden.

Public Constructor and Destructor

TPrintout(const char far* title);

virtual ~TPrintout();

Public Member Functions

virtual void BeginDocument(int startPage, int endPage, unsigned flags);

virtual void BeginPrinting();

virtual void EndDocument();

virtual void EndPrinting();

virtual void GetDialogInfo(int& minPage, int& maxPage, int& selFromPage, int& selToPage);

const char far* GetTitle() const;

virtual bool HasPage(int pageNumber);

virtual void PrintPage(int page, TRect& rect, unsigned flags);

virtual void SetPrintParams(TPrintDC* dc, TSize pageSize);

bool WantBanding()const;

bool WantForceAllBands()const;

Type Definitions

TPrintoutFlags enum

Protected Data Members

bool Banding;

TPrintDC* DC;

bool ForceAllBands;

TSize PageSize;

char far* Title;


TPrintout Public Constructor and Destructor
TPrintout Public Constructors and Destructor

TPrintout

Syntax

TPrintout(const char far* title);

Description

Constructs an instance of TPrintOut with the given title.

Destructor

virtual ~TPrintout();

Description

Destroys the resources allocated by the constructor.


TPrintout::BeginDocument

See Also	TPrintout

Syntax

virtual void BeginDocument(int startPage, int endPage, unsigned flags);

Description

The printer object's Print function calls BeginDocument once before printing each copy of a document. The flags field indicates if the current print band accepts graphics, text, or both.

The default BeginDocument does nothing. Derived objects can override BeginDocument to perform any initialization needed at the beginning of each copy of the document.


See Also

TPrintoutFlags enum


TPrintout::BeginPrinting

TPrintout

Syntax

virtual void BeginPrinting();

Description

The printer object's Print function calls BeginPrinting once at the beginning of a print job, regardless of how many copies of the document are to be printed. Derived objects can override BeginPrinting to perform any initialization needed before printing.


TPrintout::EndDocument

TPrintout

Syntax

virtual void EndDocument();

Description

The printer object's Print function calls EndDocument after each copy of the document finishes printing. Derived objects can override EndDocument to perform any needed actions at the end of each document.


TPrintout::EndPrinting

TPrintout

Syntax

virtual void EndPrinting();

Description

The printer object's Print function calls EndPrinting after all copies of the document finish printing. Derived objects can override EndPrinting to perform any needed actions at the end of each document.


TPrintout::GetDialogInfo

TPrintout

Syntax

virtual void GetDialogInfo(int& minPage, int& maxPage, int& selFromPage, int& selToPage);

Description

 Retrieves information needed to allow the printing of selected pages of the document and returns true if page selection is possible. Use of page ranges is optional, but if the page count is easy to determine, GetDialogInfo sets the number of pages in the document. Otherwise, it sets the number of pages to 0 and printing will continue until HasPage returns false.


TPrintout::GetTitle

TPrintout

Syntax

const char far* GetTitle() const;

Description

Returns the title of the current printout.


TPrintout::HasPage

TPrintout

Syntax

virtual bool HasPage(int pageNumber);

Description

HasPage is called after every page is printed. By default, it returns false, indicating that only one page is to be printed. If the document contains more than one page, this function must be overridden to return true while there are more pages to print.


TPrintout::PrintPage

TPrintout

Syntax

virtual void PrintPage(int page, TRect& rect, unsigned flags);

Description

PrintPage is called for every page (or band, if Banding is true) and must be overridden to print the contents of the given page. The rect and flags parameters are used during banding to indicate the extent and type of band currently requested from the driver (and should be ignored if Banding is false). page is the number of the current page.


TPrintout::SetPrintParams

See Also	TPrintout

Syntax

virtual void SetPrintParams(TPrintDC* dc, TSize pageSize);

Description

SetPrintParams sets DC to dc and PageSize to pageSize. The printer object's Print function calls SetPrintParams to obtain the information it needs to determine pagination and page count. Derived objects that override SetPrintParams must call the inherited function.


See Also

TPreviewPage::Paint


TPrintout::WantBanding

TPrintout

Syntax

bool WantBanding() const;

Description

Returns the value of data member Banding.


TPrintout::WantForceAllBands

TPrintout

Syntax

bool WantForceAllBands() const;

Description

Returns the value of data member ForceAllBands.


TPrintout::Banding

TPrintout

Syntax

bool Banding;

Description

If Banding is true, the printout is banded and the PrintPage function is called once for every band. Otherwise, PrintPage is called only once for every page. Banding a printout is more memory- and time-efficient than not banding. By default, Banding is set to false.


TPrintout::DC

TPrintout

Syntax

TPrintDC* DC;

Description

DC is the handle to the device context to use for printing.


TPrintout::ForceAllBands

TPrintout

Syntax

bool ForceAllBands;

Description

Many device drivers do not provide all printer bands if both text and graphics are not performed on the first band (which is typically a text-only band). Leaving ForceAllBands true forces the printer driver to provide all bands regardless of what calls are made in the PrintPage function. If PrintPage does nothing but display text, it is more efficient for ForceAllBands to be false. By default, it is true. ForceAllBands takes effect only if Banding is true.


TPrintout::PageSize

TPrintout

Syntax

TSize PageSize;

Description

PageSize is the size of the print area on the printout page.


TPrintout::Title

TPrintout

Syntax

char far* Title;

Description

Title is the current title to use for the printout. By default, this title appears in the Abort dialog box and as the name of the job in the Print Manager.


TPrintout::TPrintoutFlags enum
TPrintoutFlags enum

See Also	TPrintout

Header File

printer.h

Syntax

enum{pfGraphics, pfText, pfBoth};

Description

ObjectWindows defines the following banding constants used to set flags for printout objects.

Constant	Meaning

pfGraphics	Current band accepts only graphics.

pfText	Current band accepts only text.

pfBoth	Current band accepts both text and graphics.


See Also

TPrinter

TPrintOut


TPrintPreviewDC Class

OWL Hierarchy	Inheritance

Header File

preview.h

Description

Derived from TPrintDC, TPrintPreviewDC maps printer device coordinates to logical screen coordinates. It sets the extent of the view window and determines the screen and printer font attributes. Many of TPrintPreviewDC's functions override TDC's virtual functions.

Public Constructor and Destructor

TPrintPreviewDC(TDC& screen, TPrintDC& printdc, const TRect& client, const TRect& clip);

~TPrintPreviewDC();

Public Member Functions

int GetDeviceCaps(int index) const;

bool LPtoSDP(TPoint* points, int count = 1) const;

bool LPtoSDP(TRect& rect) const;

bool OffsetViewportOrg(const TPoint& delta, TPoint far* oldOrg = 0);

virtual void ReOrg();

virtual void ReScale();

void RestoreFont();

bool ScaleViewportExt(int xNum, int xDenom, int yNum, int yDenom, TSize far* oldExtent = 0);

bool ScaleWindowExt(int xNum, int xDenom, int yNum, int yDenom, TSize far* oldExtent = 0);

bool SDPtoLP(TPoint* points, int count = 1) const;

bool SDPtoLP(TRect& rect) const;

void SelectObject(const TFont& newFont);

void SelectStockObject(int index);

TColor SetBkColor(TColor color);

int SetMapMode(int mode);

TColor SetTextColor(TColor color);

bool SetViewportExt(const TSize& extent, TSize far* oldExtent = 0);

bool SetViewportOrg(const TPoint& origin, TPoint far* oldOrg=0);

bool SetWindowExt(const TSize& extent, TSize far* oldExtent=0);

virtual void SyncFont();

Protected Data Members

TFont* CurrentPreviewFont;

TPrintDC& PrnDC;

HFONT PrnFont;

Protected Member Functions

HDC GetAttributeHDC() const;


TPrintPreviewDC Public Constructor and Destructor

TPrintPreviewDC

Constructor

TPrintPreviewDC(TDC& screen, TPrintDC& printdc, const TRect& client, const TRect& clip);

Description

TPrintPreviewDC's constructor takes a screen DC as well as a printer DC. The screen DC is passed to the inherited constructor while the printer DC is copied to the member, PrnDC.

Destructor

~TPrintPreviewDC();

Description

Destroys a TPrintPreviewDC object.


TPrintPreviewDC::GetDeviceCaps

See Also	TPrintPreviewDC

Syntax

int GetDeviceCaps(int index) const;

Description

GetDeviceCaps returns capability information, such as font and pitch attributes, about the printer DC. The index argument specifies the type of information required.


See Also

TDC::GetDeviceCaps


TPrintPreviewDC::LPtoSDP

See Also	TPrintPreviewDC

Form 1

bool LPtoSDP(TPoint* points, int count = 1) const;

Form 2

bool LPtoSDP(TRect& rect) const;

Description

Form 1: Converts each of the count points in the points array from logical points of the printer DC to screen points. Returns a nonzero value if the call is successful; otherwise, returns 0.

Form 2: Converts each of the points in the rect from logical points of the printer DC to screen device points. Returns a nonzero value if the call is successful; otherwise, returns 0.


See Also

TPrintPreviewDC::SDPtoLP

TDC::LPtoDP


TPrintPreviewDC::OffsetViewportOrg

See Also	TPrintPreviewDC

Syntax

bool OffsetViewportOrg(const TPoint& delta, TPoint far* oldOrg = 0);

Description

Modifies this DC's viewport origin relative to the current values. The delta x- and y-components are added to the previous origin and the resulting point becomes the new viewport origin. The previous origin is saved in oldOrg. Returns nonzero if the call is successful; otherwise, returns 0.


See Also

TPrintPreviewDC::SetViewportOrg

TDC::OffsetViewportOrg


TPrintPreviewDC::ReOrg

TPrintPreviewDC

Syntax

virtual void ReOrg();

Description

Gets the x- and y- extents of the viewport, equalizes the logical and screen points, and resets the x- and y- extents of the viewport.


TPrintPreviewDC::ReScale

TPrintPreviewDC

Syntax

virtual void ReScale();

Description

Maps the points of the printer DC to the screen DC. Sets the screen window extent equal to the maximum logical pointer of the printer DC.


TPrintPreviewDC::RestoreFont

 See Also	TPrintPreviewDC

Syntax

void RestoreFont();

Description

Restores the original GDI font object to this DC.


See Also

TPrintPreviewDC::SelectObject

TDC::OrgFont


TPrintPreviewDC::ScaleViewportExt

See Also	TPrintPreviewDC

Syntax

bool ScaleViewportExt(int xNum, int xDenom, int yNum, int yDenom, TSize far* oldExtent = 0);

Description

Modifies this DC's viewport extents relative to the current values. The new extents are derived as follows:

xNewVE = (xOldVE * xNum)/ xDenom

yNewVE = (yOldVE * yNum)/ yDenom

The previous extents are saved in oldExtent. Returns nonzero if the call is successful; otherwise returns 0.


See Also

TDC::ScaleViewportExt

TPrintPreviewDC::SetViewportExt


TPrintPreviewDC::ScaleWindowExt

See Also	TPrintPreviewDC

Syntax

bool ScaleWindowExt(int xNum, int xDenom, int yNum, int yDenom, TSize far* oldExtent = 0);

Description

Modifies this DC's window extents relative to the current values. The new extents are derived as follows:

xNewWE = (xOldWE * xNum)/ xDenom

yNewWE = (yOldWE * yNum)/ yDenom

The previous extents are saved in oldExtent. Returns nonzero if the call is successful; otherwise returns 0.


See Also

TDC::SetWindowExt

TPrintPreviewDC::ScaleWindowExt


TPrintPreviewDC::SDPtoLP

See Also	TPrintPreviewDC

Form 1

bool SDPtoLP(TPoint* points, int count = 1) const;

Form 2

bool SDPtoLP(TRect& rect) const;

Description

Form 1: Converts each of the count points in the points array from screen device points to logical points of the printer DC. Returns a nonzero value if the call is successful; otherwise, returns 0.

Form 2: Converts each of the points in the rect from screen device points to logical points of the printer DC. Returns a nonzero value if the call is successful; otherwise, returns 0.


See Also

TPrintPreviewDC::LPtoSDP

TDC::DPtoLP


TPrintPreviewDC::SelectObject

See Also	TPrintPreviewDC

Syntax

void SelectObject(const TFont& newFont);

Description

Selects the given font object into this DC.


See Also

TPrintPreviewDC::SelectStockObject

TDC::SelectObject


TPrintPreviewDC::SelectStockObject

See Also	TPrintPreviewDC

Syntax

void SelectStockObject(int index);

Description

Retrieves a handle to a predefined stock font.


See Also

TDC::SelectStockObject


TPrintPreviewDC::SetBkColor

See Also	TPrintPreviewDC

Syntax

TColor SetBkColor(TColor color);

Description

Sets the current background color of this DC to the given color value or the nearest available. Returns 0x80000000 if the call fails.


See Also

TDC::SetBkColor


TPrintPreviewDC::SetMapMode

See Also	TPrintPreviewDC

Syntax

int SetMapMode(int mode);

Description

Sets the current window mapping mode of this DC to mode. Returns the previous mapping mode value. The mapping mode defines how logical coordinates are mapped to device coordinates. It also controls the orientation of the device's x- and y-axes.


See Also

TDC::GetMapMode

TDC::SetMapMode


TPrintPreviewDC::SetTextColor

See Also	TPrintPreviewDC

Syntax

TColor SetTextColor(TColor color);

Description

Sets the current text color of this DC to the given color value. The text color determines the color displayed by TDC::TextOut and TDC::ExtTextOut.


See Also

TDC::GetTextColor

TDC::SetTextColor


TPrintPreviewDC::SetViewportExt

See Also	TPrintPreviewDC

Syntax

bool SetViewportExt(const TSize& extent, TSize far* oldExtent = 0);

Description

Sets the screen's viewport x- and y-extents to the given extent values. The previous extents are saved in oldExtent. Returns nonzero if the call is successful; otherwise, returns 0. The extent value determines the amount of stretching or compression needed in the logical coordinate system to fit the device coordinate system. extent also determines the relative orientation of the two coordinate systems.


See Also

TDC::GetViewportExt

TDC::SetViewportExt


TPrintPreviewDC::SetViewportOrg

See Also	TPrintPreviewDC

Syntax

bool SetViewportOrg(const TPoint& origin, TPoint far* oldOrg=0);

Description

Sets the printer DC's viewport origin to the given origin value, and saves the previous origin in oldOrg. Returns nonzero if the call is successful; otherwise returns 0.


See Also

TPrintPreviewDC::OffsetViewportOrg

TDC::GetViewportOrg

TDC::SetViewportOrg


TPrintPreviewDC::SetWindowExt

See Also	TPrintPreviewDC

Syntax

bool SetWindowExt(const TSize& extent, TSize far* oldExtent=0);

Description

Sets the DC's window x- and y-extents to the given extent values. The previous extents are saved in oldExtent. Returns nonzero if the call is successful; otherwise, returns 0. The extent value determines the amount of stretching or compression needed in the logical coordinate system to fit the device coordinate system. extent also determines the relative orientation of the two coordinate systems.


See Also

TDC::GetWindowExt

TDC::SetWindowExt

TPrintPreviewDC::ScaleWindowExt


TPrintPreviewDC::SyncFont

TPrintPreviewDC

Syntax

virtual void SyncFont();

Description

Sets the screen font equal to the current printer font.


TPrintPreviewDC::CurrentPreviewFont

TPrintPreviewDC

Syntax

TFont* CurrentPreviewFont;

Description

The current view font.


TPrintPreviewDC::PrnDC

TPrintPreviewDC

Syntax

TPrintDC& PrnDC;

Description

Holds a reference to the printer DC.


TPrintPreviewDC::PrnFont

TPrintPreviewDC

Syntax

HFONT PrnFont;

Description

The current printer font.


TPrintPreviewDC::GetAttributeHDC

See Also	TPrintPreviewDC

Syntax

HDC GetAttributeHDC() const;

Description

Returns the attributes of the printer DC (PrnDC).


See Also

TDC::GetAttributeHDC


TProcInstance class

OWL Hierarchy

Header File

geometry.h

Description

Designed for Win16 applications, TProcInstance handles creating and freeing an instance thunk, a piece of code created for use with exported callback functions. (A callback function is a function that exists within a program but is called from outside the program by a Windows library routine, for example, a dialog box function.)

For Win32 applications, TProcInstance is non-functional. The address returned from TProcInstance can be passed as a parameter to callback functions, window subclassing functions, or Windows dialog box functions.

See the Windows API online Help for more information about MakeProcInstance, which creates an instance thunk for the function and FreeProcInstance, which frees an instance thunk. For more information about exporting callback functions, see the Borland C++ Programmer's Guide.

Public Constructor and Destructor

TProcInstance(FARPROC p);

~TProcInstance()

Public Member Function

operator FARPROC();


TProcInstance Public Constructor and Destructor
TProcInstance Public Constructors and Destructor

See Also

Syntax

TProcInstance(FARPROC p);

Destructor

~TProcInstance()

Description

Makes a TProcInstance, passing p as the address of the procedure. Under Win16, calls ::MakeProcInstance to make an instance thunk for p. Under Win32, the constructor just saves p.

Destructor

Under WIN16 frees the instance thunk.


See Also

::MakeProcInstance (Windows API)

::FreeProcInstance (Windows API)


TProcInstance::operator FARPROC

Syntax

operator FARPROC();

Description

Under WIN16, returns the instance thunk. Under Win32, returns p from the constructor.


TProfile Class

OWL Hierarchy

Header File

profile.h

Description

An instance of TProfile encapsulates a setting within a system file, often referred to as a profile or initialization file. Examples of this type of file include the Windows initialization files SYSTEM.INI and WIN.INI. Within the system file itself, the individual settings are grouped within sections. For example,

[Diagnostics]	; section name

Enabled=0    	; setting

For a setting, the value to the left of the equal sign is called the key. The value to the right of the equal sign, the value, can be either an integer or a string data type.

Public Constructor and Destructor

TProfile(const char *section, const char* filename=0);

~TProfile();

Public Member Functions

int GetInt(const char* key, int defaultInt = 0);

bool GetString(const char* key, char buff[], unsigned buffSize, const char* defaultString = "");

bool WriteInt(const char* key, int value);

bool WriteString(const char* key, const char* str);


TProfile Public Constructor and Destructor

TProfile

Constructor Syntax

TProfile(const char* section, const char* filename=0);

Description

Constructs a TProfile object for the indicated section within the profile file specified by filename.  If the file name is not provided, the file defaults to the system profile file; for example, WIN.INI under Windows .

Destructor Syntax

~TProfile();

Description

Destroys  the TProfile object.


TProfile::GetInt

TProfile

Syntax

int GetInt(const char* key, int defaultInt = 0);

Description

Looks up and returns the integer value associated with the given string, key. If key is not found, the default value, defaultInt, is returned.


TProfile::GetString

TProfile

Syntax

bool GetString(const char* key, char buff[], unsigned buffSize, const char* defaultString = "");

Description

Looks up and returns the string value associated with the given key string. The string value is copied into buff, up to buffSize bytes.  If the key is not found, defaultString  provides the default value. If a 0 key is passed, all section values are returned in buff.


TProfile::WriteInt

TProfile

Syntax

bool WriteInt(const char* key, const char* int value);

Description

Looks up the key and replaces its value with the integer value passed (int). If the key is not found, WriteInt makes a new entry. Returns true if successful.


TProfile::WriteString

TProfile

Syntax

bool WriteString(const char* key, const char* str);

Description

Looks up the key and replaces its value with the string value passed (str). If the key is not found, WriteString makes a new entry. Returns true if successful.


 TPXPictureValidator class

OWL Hierarchy	Inheritance

Header File

validate.h

Description

TPXPictureValidator objects compare user input with a picture of a data format to determine the validity of entered data. The pictures are compatible with the pictures Borland's Paradox relational database uses to control data entry. For a complete description of picture specifiers, see the Picture member function.

Public Constructor

TPXPictureValidator(const char far* pic, bool autoFill=false);

Public Member Functions

void Error();

bool IsValid(const char far* str);

bool IsValidInput(char far* str, bool suppressFill);

virtual TPicResult Picture(char far* input, bool autoFill=false);

Protected Data Member

string Pic;


TPXPictureValidator::Public Constructor
TPXPictureValidator Public Constructor

TPXPictureValidator

Syntax

TPXPictureValidator(const char far* pic, bool autoFill=false);

Description

Constructs a picture validator object by first calling the constructor inherited from TValidator and setting pic to point to it. Then sets the voFill bit in Options if AutoFill is true and sets Options to voOnAppend. Throws a TXValidator exception if the picture is invalid.


TPXPictureValidator Error
TPXPictureValidator::Error

See Also	TPXPictureValidator

Syntax

void Error();

Description

Overrides TValidator's virtual function and displays a message box that indicates an error in the picture format and displays the string pointed to by Pic.


See Also

TValidator::Error


TPXPictureValidator::IsValid

See Also	TPXPictureValidator

Syntax

bool IsValid(const char far* str);

Description

IsValid overrides TValidator's virtual function and compares the string passed in str with the format picture specified in Pic. IsValid returns true if Pic is NULL or if Picture returns Complete for str, indicating that str needs no further input to meet the specified format; otherwise, it returns false.


See Also

TPXPictureValidator::Picture


TPXPictureValidator::IsValidInput

See Also	TPXPictureValidator

Syntax

bool IsValidInput(char far* str, bool suppressFill);

Description

IsValidInput overrides TValidator's virtual function and checks the string passed in str against the format picture specified in Pic. IsValid returns true if Pic is NULL or Picture does not return Error for str; otherwise, it returns false. The suppressFill parameter overrides the value in voFill for the duration of the call to IsValidInput.

If suppressFill is false and voFill is set, the call to Picture returns a filled string based on str, so the image in the edit control automatically reflects the format specified in Pic.


See Also

TPXPictureValidator::Picture


TPXPictureValidator::Picture

TPXPictureValidator

Syntax

virtual TPicResult Picture(char far* input, bool autoFill=false);

Description

Formats the string passed in input according to the format specified by the picture string pointed to by Pic. Picture returns prError if there is an error in the picture string or if input contains data that cannot fit the specified picture. Returns prComplete if input can fully satisfy the specified picture. Returns prIncomplete if input contains data that incompletely fits the specified picture.

The following characters are used in creating format pictures:

Type of character	Character	Description

Special	#	Accept only a digit

?	Accept only a letter (case_insensitive)

&	Accept only a letter, force to uppercase

@	Accept any character

!	Accept any character, force to uppercase

Match	;	Take next character literally

*	Repetition count

[]	Option

{}	Grouping operators

,	Set of alternatives

All others	Taken literally


See Also

TPicResultenum


TPXPictureValidator::Pic

TPXPictureValidator

Syntax

string Pic;

Description

Points to a string containing the picture that specifies the format for data in the associated edit control. The constructor sets Pic to a string that is passed as one of the parameters.


TRadioButton Class

OWL Hierarchy	Inheritance

Header File

radiobut.h

Description

Defines an interface object that represents a corresponding radio button element in Windows. Use TRadioButton to create a radio button control in a parent TWindow object. A TRadioButton object can also be used to facilitate communication between your application and the radio button controls of a TDialog. object

Radio buttons have two states: checked and unchecked. TRadioButton inherits its state management member functions from its base class, TCheckBox. Optionally, a radio button can be part of a group (TGroupBox) that visually and logically groups its controls. TRadioButton is a streamable class.

Public Constructors

TRadioButton(TWindow* parent, int id, const char far* title, int x, int y, int w, int h, TGroupBox *group = 0, TModule* module = 0);

TRadioButton(TWindow* parent,int resourceId,TGroupBox *group, TModule* module = 0);

Protected Member Functions

void BNClicked();

char far* GetClassName();

Response Table Entries

EV_ macros and member functions


TRadioButton Public Constructors

See Also	TRadioButton

Syntax 1

TRadioButton(TWindow* parent, int id, const char far* title, int x, int y, int w, int h, TGroupBox *group = 0, TModule* module = 0);

Description

Constructs a radio button object with the supplied parent window (parent), control ID (id), associated text (title), position (x, y) relative to the origin of the parent window's client area, width (w), height (h), and associated group box (group). Invokes the TCheckBox constructor with similar parameters. The style is set to WS_CHILD | WS_VISIBLE | BS_AUTORADIOBUTTON.

Syntax 2

TRadioButton(TWindow* parent,int resourceId,TGroupBox *group, TModule* module = 0);

Description

Constructs a TRadioButton object to be associated with a radio button control of a TDialog object. Invokes the TCheckBox constructor with identical parameters. The resourceId parameter must correspond to a radio button resource that you define.


See Also

TControl::TControl


TRadioButton::BNClicked

See Also	TRadioButton

Syntax

void BNClicked();

Description

Responds to an incoming BN_CLICKED message.


See Also

BN_xxxx Button Message Constants


TRadioButton::GetClassName

TRadioButton

Syntax

char far* GetClassName();

Description

Returns "BUTTON", the name of the predefined radio button class.


TRadioButton Response Table Entries

TRadioButton

Response table entry	Member function

EV_MESSAGE (BM_SETSTYLE, BMSetStyle)	BMSetStyle

EV_WM_GETDLGCODE	EvGetDlgCode


TRangeValidator Class

OWL Hierarchy	Inheritance

Header File

validate.h

Description

Determines whether the data typed by a user falls within a designated range of integers. TRangeValidator is a streamable class.

Public Constructor

TRangeValidator(long min, long max);

Public Member Functions

void Error();

bool IsValid(const char far* str);

uint Transfer(char far* str, void* buffer, TTransferDirection direction);

Protected Data Members

long Max;

long Min;


TRangeValidator Public constructor

See Also	TRangeValidator

Syntax

TRangeValidator(long min, long max);

Description

Constructs a range validator object by first calling the constructor inherited from TFilterValidator, passing a set of characters containing the digits '0'..'9' and the characters '+' and '-'. Sets Min to min and Max to max, establishing the range of acceptable long integer values.


See Also

TFilterValidator::TFilterValidator


TRangeValidator Error
TRangeValidator::Error

TRangeValidator

Syntax

void Error();

Description

Overrides TValidator's virtual function and displays a message box indicating that the entered value does not fall within the specified range.


TRangeValidator::IsValid

TRangeValidator

Syntax

bool IsValid(const char far* str);

Description

Converts the string str into an integer number and returns true if the result meets all three of these conditions:

It is a valid integer number.

Its value is greater than or equal to min.

Its value is less than or equal to max.

If any of those tests fails, IsValid returns false.


TRangeValidator::Transfer

See Also	TRangeValidator

Syntax

uint Transfer(char far* str, void* buffer, TTransferDirection direction);

Description

Incorporates the three types, tdSizeData, tdGetData, and tdSetData, that a range validator can handle for its associated edit control. The parameter str is the edit control's string value, and buffer is the data passed to the edit control. Depending on the value of direction, Transfer either sets str from the number in buffer or sets the number at buffer to the value of the string str. If direction is tdSetData, Transfer sets str from buffer. If direction is tdGetData, Transfer sets buffer from str. If direction is tdSizeData, Transfer neither sets nor reads data.

Transfer always returns the size of the data transferred.


See Also

TTransferDirection enum

TWindow::Transfer


TRangeValidator::Max

TRangeValidator

Syntax

long Max;

Description

Max is the highest valid long integer value for the edit control.


TRangeValidator::Min

TRangeValidator

Syntax

long Min;

Description

Min is the lowest valid long integer value for the edit control.


TRect Class

OWL Hierarchy

Header File

geometry.h

Description

TRect is a mathematical class derived from tagRect. The tagRect  struct is defined as

struct tagRECT {

   int left;

   int top;

   int right;

   int bottom;

};

TRect encapsulates the properties of rectangles with sides parallel to the x- and y-axes. In ObjectWindows, these rectangles define the boundaries of windows, boxes, and clipping regions. TRect inherits four data members from tagRect left, top, right, and bottom. These represent the top left and bottom right (x, y) coordinates of the rectangle. Note that x increases from left to right, and y increases from top to bottom.

TRect places no restrictions on the relative positions of top left and bottom right, so it is legal to have left > right and top > bottom. However, many manipulations--such as determining width and height, and forming unions and intersections--are simplified by normalizing the TRect objects involved. Normalizing a rectangle means interchanging the corner point coordinate values so that left < right and top < bottom. Normalization does not alter the physical properties of a rectangle. myRect.Normalized creates normalized copy of myRect without changing myRect, while myRect.Normalize changes myRect to a normalized format. Both members return the normalized rectangle.

TRect constructors are provided to create rectangles from either four ints, two TPoint objects, or one TPoint and one TSize object. In the latter case, the TPoint object specifies the top left point (also known as the rectangle's origin) and the TSize object supplies the width and height of the rectangle. Member functions perform a variety of rectangle tests and manipulations. Overloaded << and >> operators allow chained insertion and extraction of TRect objects with streams.

Public Constructors

TRect();

TRect(const RECT far& rect);

TRect(int _left, int _top, int _right, int _bottom);

TRect(const TPoint& upLeft, const TPoint& loRight);

TRect(const TPoint& origin, const TSize& extent);

Public Member Functions

long Area() const;

TPoint BottomLeft() const;

const TPoint& BottomRight() const;

TPoint& BottomRight();

bool Contains(const TPoint& point) const;

bool Contains(const TRect& other) const;

int Height() const;

TRect& Inflate(int dx, int dy);

TRect& Inflate(const TSize& size delta);

TRect InflatedBy(int dx, int dy) const;

TRect InflatedBy(const TSize& size) const;

bool IsEmpty() const;

bool IsNull() const;

TRect& Normalize();

TRect Normalized() const;

TRect& Offset(int dx, int dy);

TRect OffsetBy(int dx, int dy) const;

TRect operator +(const TSize& size) const;

TRect operator -(const TSize& size) const;

TRect operator &(const TRect& other) const;

TRect operator |(const TRect& other) const;

bool operator ==(const TRect& other) const;

bool operator !=(const TRect& other) const;

TRect& operator +=(const TSize& delta);

TRect& operator -=(const TSize& delta);

TRect& operator &=(const TRect& other);

TRect& operator |=(const TRect& other);

operator const TPoint*() const;

operator TPoint*();

void Set(int _left, int _top, int _right, int _bottom);

void SetEmpty();

void SetNull();

TSize Size() const;

const TPoint& TopLeft() const;

TPoint& TopLeft();

TPoint TopRight() const;

bool Touches(const TRect& other) const;

int Width() const;

ipstream& _BIDSFUNC operator >>(ipstream& is, TRect& r);

opstream& _BIDSFUNC operator <<(opstream& os, const TRect& r);

ostream& _BIDSFUNC operator <<(ostream& os, const TRect& r);


TRect Public Constructors

See Also	TRect

Constructors

Syntax 1

TRect();

Description

The default constructor.

Syntax 2

TRect(const RECT far& rect);

Description

Copies the given rect to this object.

Syntax 3

TRect(int _left, int _top, int _right, int _bottom);

Description

Creates a rectangle with the given values.

Syntax 4

TRect(const TPoint& upLeft, const TPoint& loRight);

Description

Creates a rectangle with the given top left and bottom right points.

Syntax 5

TRect(const TPoint& origin, const TSize& extent);

Description

Creates a rectangle with its origin (top left) at origin, width at extent.cx, height at extent.cy.


See Also

TPoint

TSize


TRect Area
TRect::Area

See Also	TRect

Syntax

long Area() const;

Description

Returns the area of this rectangle.


See Also

TRect::Size


TRect::BottomLeft

See Also	TRect

Syntax

TPoint BottomLeft() const;

Description

Returns the TPoint object representing the bottom left corner of this rectangle.


See Also

TRect::TopLeft

TRect::TopRight

TRect::BottomRight

TPoint


TRect::BottomRight

See Also	TRect

Syntax 1

const TPoint& BottomRight() const;

Syntax 2

TPoint& BottomRight();

Description

Returns the TPoint object representing the bottom right corner of this rectangle.


See Also

TRect::TopRight

TRect::BottomLeft

TRect::TopLeft

TPoint


TRect::Contains

See Also	TRect

Syntax 1

bool Contains(const TPoint& point) const;

Description

Returns true if the given point lies within this rectangle; otherwise, it returns false. If point is on the left vertical or on the top horizontal borders of the rectangle, Contains also returns true, but if point is on the right vertical or bottom horizontal borders, Contains returns false.

Syntax 2

bool Contains(const TRect& other) const;

Description

Returns true if the other rectangle lies on or within this rectangle; otherwise, it returns false.


See Also

TRect::Touches

TPoint

TRect


TRect::Height

See Also	TRect

Syntax

int Height() const;

Description

Returns the height of this rectangle (bottom - top).


See Also

TRect::Width


TRect::Inflate

See Also	TRect

Syntax 1

TRect& Inflate(int dx, int dy);

Syntax 2

TRect& Inflate(const TSize& delta);

Description

Inflates a rectangle inflated by the given delta arguments. In the first version, the top left corner of the returned rectangle is (left - dx, top - dy), while its bottom right corner is (right + dx, bottom + dy). In the second version the new corners are (left - size.cx, top - size.cy) and (right + size.cx, bottom + size.cy).


See Also

TRect

TSize


TRect::InflatedBy

See Also	TRect

Syntax 1

TRect InflatedBy(int dx, int dy) const;

Syntax 2

TRect InflatedBy(const TSize& size) const;

Description

Returns a rectangle inflated by the given delta arguments. In the first version, the top left corner of the returned rectangle is (left - dx, top - dy), while its bottom right corner is (right + dx, bottom + dy). In the second version the new corners are (left - size.cx, top - size.cy) and (right + size.cx, bottom + size.cy). The calling rectangle object is unchanged.


See Also

TRect::OffsetBy

TRect

TSize


TRect::IsEmpty

See Also	TRect

Syntax

bool IsEmpty() const;

Description

Returns true if left >= right or top >= bottom; otherwise, returns false.


See Also

TRect::SetEmpty

TRect::IsNull


TRect::IsNull

See Also	TRect

Syntax

bool IsNull() const;

Description

Returns true if left, right, top, and bottom are all 0; otherwise, returns false.


See Also

TRect::IsEmpty

TRect::SetEmpty


TRect::Normalize

See Also	TRect

Syntax

TRect& Normalize();

Description

Normalizes this rectangle by switching the left and right data member values if left > right, and switching the top and bottom data member values if top > bottom. Normalize returns the normalized rectangle. A valid but nonnormal rectangle might have left > right or top > bottom or both. In such cases, many manipulations (such as determining width and height) become unnecessarily complicated. Normalizing a rectangle means interchanging the corner point values so that left < right and top < bottom. The physical properties of a rectangle are unchanged by this process.


See Also

TRect::Normalized

TRect


TRect::Normalized

See Also	TRect

Syntax

TRect Normalized() const;

Description

Returns a normalized rectangle with the top left corner at (Min(left, right), Min(top, bottom)) and the bottom right corner at (Max(left, right), Max(top, bottom)). The calling rectangle object is unchanged. A valid but nonnormal rectangle might have left > right or top > bottom or both. In such cases, many manipulations (such as determining width and height) become unnecessarily complicated. Normalizing a rectangle means interchanging the corner point values so that left < right and top < bottom. The physical properties of a rectangle are unchanged by this process.

Note that many calculations assume a normalized rectangle. Some Windows API functions behave erratically if an inside-out Rect is passed.


See Also

TRect::Normalize

TRect


TRect::Offset

See Also	TRect

Syntax

TRect& Offset(int dx, int dy);

Description

Changes this rectangle so its corners are offset by the given delta values. The revised rectangle has a top left corner at (left + dx, top + dy) and a right bottom corner at (right + dx, bottom + dy). The revised rectangle is returned.


See Also

TRect::operator +

TRect::operator +=

TRect::OffsetBy


TRect::OffsetBy

See Also	TRect

Syntax

TRect OffsetBy(int dx, int dy) const;

Description

Returns a rectangle with the corners offset by the given delta values. The returned rectangle has a top left corner at (left + dx, top + dy) and a right bottom corner at (right + dx, bottom + dy).


See Also

TRect::operator +


TRect::operator +

See Also	TRect

Syntax

TRect operator +(const TSize& size) const;

Description

Returns a rectangle offset positively by the delta values' given sizes. The returned rectangle has a top left corner at (left + size.x, top + size.y) and a right bottom corner at (right + size.x, bottom + size.y). The calling rectangle object is unchanged.


See Also

TRect::OffsetBy

TSize


TRect::operator -

See Also	TRect

Syntax

TRect operator -(const TSize& size) const;

Description

Returns a rectangle offset negatively by the delta values' given sizes. The returned rectangle has a top left corner at (left - size.cx, top - size.cy) and a right bottom corner at (right - size.cx, bottom - size.cy). The calling rectangle object is unchanged.


See Also

TRect::OffsetBy

TSize


TRect::operator &

See Also	TRect

Syntax

TRect operator &(const TRect& other) const;

Description

Returns the intersection of this rectangle and the other rectangle. The calling rectangle object is unchanged. Returns a NULL rectangle if the two don't intersect.


See Also

TRect::operator |

TRect::operator &=


TRect::operator |

See Also	TRect

Syntax

TRect operator |(const TRect& other) const;

Description

Returns the union of this rectangle and the other rectangle. The calling rectangle object is unchanged.


See Also

TRect::operator &

TRect::operator |=


TRect::operator ==

See Also	TRect

Syntax

bool operator ==(const TRect& other) const;

Description

Returns true if this rectangle has identical corner coordinates to the other rectangle; otherwise, returns false.


See Also

TRect::operator !=


TRect::operator !=

See Also	TRect

Syntax

bool operator !=(const TRect& other) const;

Description

Returns false if this rectangle has identical corner coordinates to the other rectangle; otherwise, returns true.


See Also

TRect::operator ==


TRect::operator +=

See Also	TRect

Syntax

TRect& operator +=(const TSize& delta);

Description

Changes this rectangle so its corners are offset by the given delta values, delta.x and delta.y. The revised rectangle has a top left corner at (left + delta.x, top + delta.y) and a right bottom corner at (right + delta.x, bottom + delta.y). The revised rectangle is returned.


See Also

TRect::operator +

TRect::OffsetBy

TRect::Offset


TRect::operator -=

See Also	TRect

Syntax

TRect& operator -=(const TSize& delta);

Description

Changes this rectangle so its corners are offset negatively by the given delta values, delta.x and delta.y. The revised rectangle has a top left corner at (left - delta.x, top - delta.y) and a right bottom corner at (right - delta.x, bottom - delta.y). The revised rectangle is returned.


See Also

TRect::operator -

TRect::operator +=

TRect::OffsetBy

TRect::Offset


TRect::operator &=

See Also	TRect

Syntax

TRect& operator &=(const TRect& other);

Description

Changes this rectangle to its intersection with the other rectangle. This rectangle object is returned. Returns a NULL rectangle if there is no intersection.


See Also

TRect::operator &

TRect::operator |=


TRect::operator |=

See Also	TRect

Syntax

TRect& operator |=(const TRect& other);

Description

Changes this rectangle to its union with the other rectangle. This rectangle object is returned.


See Also

TRect::operator |

TRect::operator &=


TRect::operator TPoint*()

See Also	TRect

Form 1

operator const TPoint*() const;

Form 2

operator TPoint*()

Description

Type conversion operators converting the pointer to this rectangle to type pointer to TPoint.


See Also

TPoint


TRect::Set

TRect

Syntax

void Set(int _left, int _top, int _right, int _bottom);

Description

Repositions and resizes this rectangle to the given values.


TRect::SetEmpty

TRect

Syntax

void SetEmpty();

Description

Empties this rectangle by setting left, top, right, and bottom to 0.


TRect::SetNull

TRect

Syntax

void SetNull();

Description

Sets the left, top, right, and bottom of the rectangle to 0.


TRect::Size

See Also	TRect

Syntax

TSize Size() const;

Description

Returns a TSize object representing the width and height of this rectangle.


See Also

TSize


TRect::TopLeft

See Also	TRect

Syntax 1

const TPoint& TopLeft() const;

Syntax 2

TPoint& TopLeft();

Description

Returns the TPoint object representing the top left corner of this rectangle.


See Also

TRect::TopRight

TRect::BottomLeft

TRect::BottomRight

TPoint


TRect::TopRight

See Also	TRect

Syntax

TPoint TopRight() const;

Description

Returns the TPoint object representing the top right corner of this rectangle.


See Also

TRect::TopLeft

TRect::BottomLeft

TRect::BottomRight


TRect::Touches

See Also	TRect

Syntax

bool Touches(const TRect& other) const;

Description

Returns true if the other rectangle shares any interior points with this rectangle; otherwise, returns false.


See Also

TRect::Contains


TRect::Width

See Also	TRect

Syntax

int Width() const;

Description

Returns the width of this rectangle (right - left).


See Also

TRect::Height


TRect::operator >>

See Also	TRect

Syntax

ipstream& _BIDSFUNC operator >>(ipstream& is, TRect& r);

Description

Extracts a TRect object from is, the given input stream, and copies it to r. Returns a reference to the resulting stream, allowing the usual chaining of >> operations.


See Also

TRect operator <<


TRect::operator <<

See Also	TRect

Syntax 1

opstream& _BIDSFUNC operator <<(opstream& os, const TRect& r);

Description

Inserts the given TRect object, r, into the opstream, os. Returns a reference to the resulting stream, allowing the usual chaining of << operations.

Syntax 2

ostream& _BIDSFUNC operator <<(ostream& os, const TRect& r);

Description

Formats and inserts the given TRect object, r, into the ostream, os. The format is (r.left, r.top)(r.right, r.bottom). Returns a reference to the resulting stream and allows the usual chaining of << operations.


See Also

TRect operator >>


TRegion class

OWL Hierarchy	Inheritance

Header File

gdiobjec.h

Description

TRegion, derived from TGdiObject, represents GDI abstract shapes or regions. TRegion can construct region objects with various shapes. Several operators are provided for combining and comparing regions.

Type Definitions

enum TEllipse{Ellipse};

Public Constructors

TRegion();

TRegion(HRGN handle,TAutoDelete autoDelete = NoAutoDelete);

TRegion(const TRegion& region);

TRegion(const TRect& rect);

TRegion(const TRect& E, TEllipse);

TRegion(const TRect& rect, const TSize& corner);

TRegion(const TPoint* points,int count,int fillMode);

TRegion(const TPoint* points, const int* polyCounts, int count,int fillMode);

Public Member Functions

bool Contains(const TPoint& point) const;

int GetRgnBox(TRect& box) const;

TRect GetRgnBox() const;

bool operator ==(const TRegion& other) const;

bool operator !=(const TRegion& other) const;

TRegion& operator =(const TRegion& source);

TRegion& operator +=(const TSize& delta);

TRegion& operator -=(const TSize& delta);

TRegion& operator -=(const TRegion& source);

TRegion& operator &=(const TRegion& source);

TRegion& operator &=(const TRect& source);

TRegion& operator |=(const TRegion& source);

TRegion& operator |=(const TRect& source);

TRegion& operator ^=(const TRegion& source);

TRegion& operator ^=(const TRect& source);

operator HRGN() const;

void SetRectRgn(const TRect& rect);

bool Touches(const TRect& rect) const;


TRegion::enum TEllipse

See Also	TRegion

Syntax

enum TEllipse{Ellipse};

Description

Defines the class-specific constant Ellipse, used to distinguish the ellipse constructor from the rectangle copy constructor.


See Also

TRegion::TRegion


TRegion Public Constructors

See Also	TRegion

Syntax 1

TRegion();

Description

The default constructor creates an empty TRegion object. Handle is set to 0 and ShouldDelete is set to true.

Syntax 2

TRegion(HRGN handle,TAutoDelete autoDelete = NoAutoDelete);

Description

Creates a TRegion object and sets the Handle data member to the given borrowed handle. The ShouldDelete data member defaults to false, ensuring that the borrowed handle is not deleted when the C++ object is destroyed. HRGN is the data type representing the handle to an abstract shape.

Syntax 3

TRegion(const TRegion& region);

Description

This public copy constructor creates a copy of the given TRegion object as in:

TRegion myRegion = yourRegion;

Syntax 4

TRegion(const TRect& rect);

Description

Creates a region object from the given TRect object as in:

TRegion myRegion(rect1);

TRegion* pRegion;

pRegion = new TRegion(rect2);

Syntax 5

TRegion(const TRect& E, TEllipse);

Description

Creates the elliptical TRegion object that inscribes the given rectangle E. The TEllipse argument distinguishes this constructor from the TRegion(const TRect& rect) constructor.

Syntax 6

TRegion(const TRect& rect, const TSize& corner);

Description

Creates a TRegion object from the given rect corner.

Syntax 7

TRegion(const TPoint* points,int count,int fillMode);

Description

Creates a filled TRegion object from the polygons given by points and fillMode.

Syntax 8

TRegion(const TPoint* points, const int* polyCounts,

        int count,int fillMode);

Description

Creates a filled TRegion object from the polygons given by points and fillMode.


See Also

TGdiObject::Handle

TGdiObject::ShouldDelete

TPoint

TRect

TSize


TRegion::Contains

See Also	TRegion

Syntax

bool Contains(const TPoint& point) const;

Description

Returns true if this region contains the given point.


See Also

TPoint


TRegion::GetRgnBox

See Also	TRegion

Syntax 1

int GetRgnBox(TRect& box) const;

Description

Finds the bounding rectangle (the minimum rectangle containing this region). The resulting rectangle is placed in box and the returned values are as follows:

Value	Meaning

COMPLEXREGION	Region has overlapping borders.

NULLREGION	Region is empty.

SIMPLEREGION	Region has no overlapping borders.

Syntax 2

TRect GetRgnBox() const;

Description

Returns the resulting rectangle.


See Also

TRect


TRegion::operator ==

See Also	TRegion

Syntax

bool operator ==(const TRegion& other) const;

Description

Returns true if this region is equal to the other region.


See Also

TRegion::operator !=


TRegion::operator !=

See Also	TRegion

Syntax

bool operator !=(const TRegion& other) const;

Description

Returns true if this region is not equal to the other region.


See Also

TRegion::operator ==


TRegion::operator =

TRegion

Syntax

TRegion& operator =(const TRegion& source);

Description

Assigns the source region to this region. A reference to the result is returned, allowing chained assignments.


TRegion::operator +=

See Also	TRegion

Syntax

TRegion& operator +=(const TSize& delta);

Description

Adds the given delta to each point of this region to displace (translate) it by delta.x and delta.y. Returns a reference to the resulting region.


See Also

TSize

TRegion::operator -=


TRegion::operator -=

See Also	TRegion

Form 1

TRegion& operator -=(const TSize& delta);

Form 2

TRegion& operator -=(const TRegion& source);

Description

The first form subtracts the given delta from each point of this region to displace (translate) it by -delta.x and -delta.y. The second form creates a "difference" region consisting of all parts of this region that are not parts of the source region. Both forms return a reference to the resulting region.


See Also

TSize

TRegion::operator +=


TRegion::operator &=

See Also	TRegion

Form 1

TRegion& operator &=(const TRegion& source);

Form 2

TRegion& operator &=(const TRect& source);

Description

Creates the intersection of this region with the given source region or rectangle, and returns a reference to the result.


See Also

TRect


TRegion::operator |=

See Also	TRegion

Form 1

TRegion& operator |=(const TRegion& source);

Form 2

TRegion& operator |=(const TRect& source);

Description

Creates the union of this region and the given source region or rectangle, and returns a reference to the result.


See Also

TRect


TRegion::operator ^=

See Also	TRegion

Form 1

TRegion& operator ^=(const TRegion& source);

Form 2

TRegion& operator ^=(const TRect& source);

Description

Creates the union of this region and the given source region or rectangle, but excludes any overlapping areas. Returns a reference to the resulting region object.


See Also

TRect


TRegion::operator HRGN()

TRegion

Syntax

operator HRGN() const;

Description

Typecast operator. HRGN is the data type representing the handle to a physical region.


TRegion::SetRectRgn

See Also	TRegion

Syntax

void SetRectRgn(const TRect& rect);

Description

Creates a rectangle of the size given by rect.


See Also

TRect


TRegion::Touches

See Also	TRegion

Syntax

bool Touches(const TRect& rect) const;

Description

Returns true if this region touches the given rectangle.


See Also

TRect


TRegItem Struct

See Also

Header File

locale.h

Description

TRegItem defines localizable values for parameters or subkeys. These values can be passed to TLocaleString, which defines a localizable substitute for char*. TRegItem contains several undocumented functions that are used privately by the registration macros REGFORMAT and REGSTATUS.

Public Data Members

char* Key;

TLocaleString Value;


See Also

Registration Macros

TRegLink Struct

TRegList Class


TRegItem::Key

See Also	TRegItem

Syntax

char* Key;

Description

Contains a non-localizable item name, such as clsid or progid.


See Also

Registration Macros

TLocaleString struct


TRegItem::Value

See Also	TRegItem

Syntax

TLocaleString Value;

Description

Contains a localizable value (for example, "My Sample App") associated with an item name.


See Also

Registration Macros

TLocaleString struct


TRelationship enum

OWL Hierarchy	See Also

Header File

layoutco.h

Syntax

enum TRelationship {lmAsIs, lmPercentOf, lmAbove, lmLeftOf = lmAbove, lmBelow, lmRightOf = lmBelow, lmSameAs, lmAbsolute};

Description

Used by the TLayoutConstraint struct, TRelationship specifies the relationship between the edges and sizes of one window and the edges and sizes of another window (which can be a parent or sibling). These relationships can be specified as either the same value as the sibling or parent window (lmAsIs), an absolute value (lmAbsolute), a percent of one of the windows (lmPercentOf), a value that is either added above (lmAbove) or left (lmLeftOf) of one of the windows, or a value that is subtracted from below (lmBelow) or right (lmRightOf) of one of the windows.


See Also

TLayoutConstraint struct


TRegLink Struct

See Also

Header File

locale .h

Description

TRegLink is a linked structure in which each node points to a list of TRegList objects (or TRegList-derived objects) or TDocTemplate objects. Each object has an item name and a string value associated with the item name. The structure forms a typical linked list as the following diagram illustrates:

A TDocTemplate object uses the following variation of the TRegLink structure:

Public Data Members

TRegList* RegList;

TRegLink* NextLink;


See Also

Registration Macros

TLocaleString struct

TRegItem struct


TRegLink::RegList

See Also	TRegLink

Syntax

TRegList* RegList;

Description

Points to the list of item value pairs.


See Also

Registration Macros


TRegLink::NextLink

See Also	TRegLink

Syntax

TRegLink* NextLink;

Description

Points to the next link that references a list of items.


See Also

Registration Macros


TRegList Class

See Also

Header File

locale .h

Description

Holds an array of items of type TRegItem. Provides functionality that lets you access each item in the array and return the name of the item. Instead of creating a TRegList directly, you can use ObjectWindows' registration macros to build a TRegList for you.

Public Data Members

TRegItem* Items;

const char* operator [](const char* key);

Public Constructors

TRegList(TRegItem* list):Items(List);

Public Member Functions

const char* Lookup(const char* key, TLangId lang = TLocaleString::UserDefaultLangId);

TLocaleString& LookupRef(const char* key);


See Also

Registration Macros

TLocaleString struct

TRegLink Class


TRegList::Items

See Also	TRegList

Syntax

TRegItem* Items;

Description

References the item value pair respectively; for example, Prgid and "My Sample Application".


See Also

Registration Macros


TRegList::Operator [ ]

TRegList

Syntax

const char* operator[](const char* key);

Description

The array operator uses an item name (key) to locate an item in the array.


TRegList Public Constructors
TRegList Public Constructor

See Also	TRegList

Syntax

TRegList(TRegItem* list):Items(List);

Description

Constructs a TRegList object from an array of TRegItems terminated by a NULL item name.


See Also

Registration Macros


TRegList::Lookup

See Also	TRegList

Syntax

const char* Lookup(const char* key, TLangId lang = TLocaleString::UserDefaultLangId);

Description

Performs the lookup of the TRegItems using a key (an item name such as progid) and returns the value associated with the key (for example, "My Sample Application"). The value is returned in the language specified in lang (for example, French Canadian).


See Also

TLangId

TLocaleString struct


TRegList::LookupRef

See Also	TRegList

Syntax

TLocaleString& LookupRef(const char* key);

Description

Looks up and returns a reference to a local string value associated with a particular item name (key). You can then translate this string into the local language as necessary.


See Also

Registration Macros

TLocaleString struct


TReplaceDialog::TReplaceDialog Class
TReplaceDialog Class

OWL Hierarchy	Inheritance

Header File

findrepl.h

Description

TReplaceDialog creates a modeless dialog box that lets the user enter a selection of text to replace. Because these are model dialog boxes, you can search for text, edit the text in the window, and return to the dialog box to enter another selection. TReplaceDialog uses the TFindReplaceDialog::TData class to set the user-defined values for the dialog box, such as the text strings to search for and replace.

Public Constructor

TReplaceDialog(TWindow* parent, TData& data, TResID templateName=0, const char far* title=0, TModule* module=0);

Protected Member Function

HWND DoCreate();


TReplaceDialog Public Constructor

See Also	TReplaceDialog

Syntax

TReplaceDialog(TWindow* parent, TData& data, TResID templateName=0, const char far* title=0, TModule* module=0);

Description

Constructs a TReplaceDialog object with a parent window, resource ID, template name, caption, and module instance. The data  parameter is a reference to the TFindReplaceDialog::TData class that contains information about the appearance and functionality of the dialog box, such as the user-entered text strings to search for and replace.


See Also

TFindReplaceDialog::TData


TReplaceDialog::DoCreate

See Also	TReplaceDialogclass

Syntax

HWND DoCreate();

Description

Creates a modeless find and replace dialog box.


See Also

TDialog::DoCreate


TResId Class

OWL Hierarchy

Header File

geometry.h

Description

A simple support class, TResId creates a resource ID object from either an integer or an actual string identifier. For example, TResId encapsulates the use of LPSTR (char_far*) as a resource identifier. This resource identifier can be passed to various ObjectWindows classes. To handle these two different types of resource identifiers, TResId defines a conversion operator and provides two constructors that convert and use these native data types. One constructor accepts a 16-bit integer and the other accepts a character string.

Public Constructors

TResId();

TResId(int resNum);

TResId(const char far* resString);

Public Member Functions

operator char far*();

bool IsString() const;

Friend Functions

friend ipstream& operator >>(ipstream& is, TResId& id);

friend opstream& operator <<(opstream& os, const TResId& id);

friend ostream& operator <<(ostream& os, const TResId& id);


TResId Public Constructors

TResId

Syntax 1

TResId();

Description

The default TResId constructor.

Syntax 2

TResId(int resNum);

Description

Creates a TResId object with the given resNum.

Syntax 3

TResId(const char far* resString);

Description

Creates a TResId object with the given resString.


TResId::IsString

TResId

Syntax

bool IsString() const;

Description

Returns true if this resource ID was created from a string; otherwise, returns false.


TResId::operator char far*()

TResId

Syntax

operator char far*();

Description

Typecasting operator that converts Id (a TResId private data member) to type char far* so that instances of TResId can be used in places where char far* data types are expected.


TResId::operator >>

See Also	TResId

Syntax

friend ipstream& operator >>(ipstream& is, TResId& id);

Description

Extracts a TResId object from is (the given input stream), and copies it to id. Returns a reference to the resulting stream, allowing the usual chaining of >> operations.


See Also

TResId friend operator <<


TResId::operator <<

See Also	TResId

Syntax 1

friend opstream& operator <<(opstream& os, const TResId& id);

Description

Inserts the given TResId object (id) into the opstream (os). Returns a reference to the resulting stream, allowing the usual chaining of << operations.

Syntax 2

friend ostream& operator <<(ostream& os, const TResId& id);

Description

Formats and inserts the given TResId object (id) into the ostream (os). Returns a reference to the resulting stream, allowing the usual chaining of << operations.


See Also

TResId friend operator >>


TResponseTableEntry Class

OWL Hierarchy

Header File

eventhan.h

Description

A template class, TResponseTableEntry lets you define a pattern for entries into a response table. Entries consist of a message, a notification code, a resource ID, a dispatcher type, and a pointer to a member function.

See DECLARE_RESPONSE_TABLE and DEFINE_RESPONSE_TABLE for additional information about the macros in the response tables.

Public Data Members

TAnyDispatcher Dispatcher;

uint Id;

uint Msg;

uint NotifyCode;

PMF Pmf;

Type Definitions

typedef void(T::*PMF)();


TResponseTableEntry::Dispatcher

TResponseTableEntry

Syntax

TAnyDispatcher Dispatcher;

Description

An abstract dispatcher type that points to one of the dispatcher functions.


TResponseTableEntry::Id

TResponseTableEntry

Syntax

uint Id;

Description

Contains the menu or accelerator resource ID (CM_xxxx) for the message response member function.


TResponseTableEntry::Msg

TResponseTableEntry

Syntax

uint Msg;

Description

Contains the ID of the message sent. These can be command messages, child id messages, notify-based messages such as LBN_SELCHANGE, or messages such as LBUTTONDOWN.


TResponseTableEntry::NotifyCode

TResponseTableEntry

Syntax

uint NotifyCode;

Description

Stores the control notification code (for example, ID_LISTBOX) for the response table entry. These can be button, combo box, edit control, or list box notification codes.


TResponseTableEntry::Pmf

TResponseTableEntry

Syntax

PMF Pmf;

Description

Points to the actual handler or member function.


TResponseTableEntry::T

TResponseTableEntry

Syntax

typedef void(T_*PMF)();

Description

Type for a generic member function that responds to notification messages. T is the template for the response table.


TRgbQuad class

OWL Hierarchy

Header File

color.h

Description

TRgbQuad is a support class derived from the structure tagRGBQUAD, which is defined as follows:

typedef struct tagRGBQUAD {

   uint8  rgbBlue;

   uint8  rgbGreen;

   uint8  rgbRed;

   uint8  rgbReserved;

} RGBQUAD;

The elements rgbBlue, rgbGreen, and rgbRed specify the relative blue, green, and red intensities of a color. rgbReserved is not used and must be set to 0.

TRgbQuad is used in conjunction with the classes TPalette and TColor to simplify RGBQUAD-based color operations. Constructors are provided to create TRgbQuad objects from explicit RGB values, from TColor objects, or from other TRgbQuad objects.

Public Constructors

TRgbQuad(int r, int g, int b);

TRgbQuad(TColor c);

TRgbQuad(const RGBQUAD far& q);


TRGBQuad Public Constructors

TRGBQuad	See Also

Syntax 1

TRgbQuad(int r, int g, int b);

Description

Creates a TRgbQuad object with rgbRed, rgbGreen, and rgbBlue set to r, g, and b respectively. Sets rgbReserved to 0.

Syntax 2

TRgbQuad(TColor c);

Description

Creates a TRgbQuad object with rgbRed, rgbGreen, rgbBlue set to c.Red, c.Green, c.Blue respectively. Sets rgbReserved to 0.

Syntax 3

TRgbQuad(const RGBQUAD far& q);

Description

Creates a TRgbQuad object with the same values as the referenced RGBQUAD object.


See Also

TColor::Red

TColor::Green

TColor::Blue


TRgbTriple Class

OWL Hierarchy

Header File

color.h

Description

TRgbTriple is a support class derived from the structure tagRgbTriple, which is defined as follows:

typedef struct tagRGBTRIPLE {

    uint8  rgbBlue;

    uint8  rgbGreen;

    uint8  rgbRed;

} RGBTRIPLE;

The members rgbBlue, rgbGreen, and rgbRed specify the relative blue, green, and red intensities for a color.

TRgbTriple is used in conjunction with the classes TPalette and TColor to simplify bmci-color-based operations. Constructors are provided to create TRgbTriple objects from explicit RGB values, from TColor objects, or from other TRgbTriple objects.

Public Constructors

TRgbTriple(int r, int g, int b);

TRgbTriple(TColor c);

TRgbTriple(const RGBTRIPLE far& t);


TRgbTriple Public Constructors

See Also

Syntax 1

TRgbTriple(int r, int g, int b);

Description

Creates a TRgbTriple object with rgbRed, rgbGreen, and rgbBlue set to r, g, and b respectively.

Syntax 2

TRgbTriple(TColor c);

Description

Creates a TRgbTriple object with rgbRed, rgbGreen, rgbBlue set to c.Red, c.Green, and c.Blue respectively.

Syntax 3

TRgbTriple(const RGBTRIPLE far& t);

Description

Creates a TRgbTriple object with the same values as the referenced RGBTRIPLE object.


See Also

tag RGBTRIPLE struct

TColor::Red

TColor::Green

TColor::Blue


TScreenDC::TScreenDC Class
TScreenDC Class

OWL Hierarchy	Inheritance

Header File

dc.h

Description

Derived from TWindowDC, TScreenDC is a DC class that provides direct access to the screen bitmap. TScreenDC gets a DC for handle 0, which is for the whole screen with no clipping. Handle 0 paints on top of other windows.

Public Constructors

TScreenDC();


TScreenDC Public Constructor

TScreenDC

Syntax

TScreenDC();

Description

Default constructor for TScreenDC objects.


TScrollBar Class

OWL Hierarchy	Inheritance

Header File

scrollba.h

Description

TScrollBar objects represent standalone vertical and horizontal scroll bar controls. Most of TScrollBar's member functions manage the scroll bar's sliding box (thumb) position and range.

One special feature of TScrollBar is the notify-based set of member functions that automatically adjust the scroll bar's thumb position in response to scroll bar messages.

Never place TScrollBar objects in windows that have either the WS_HSCROLL or WS_VSCROLL styles in their attributes.

TScrollBar is a streamable class.

Public Data Members

int LineMagnitude;

int PageMagnitude;

Public Constructors

TScrollBar(TWindow* parent, int id, int x, int y, int w, int h, bool isHScrollBar, TModule* module = 0);

TScrollBar(TWindow* parent,int resourceId,TModule* module = 0);

Public Member Functions

virtual int DeltaPos(int delta);

void EvHScroll(uint scrollCode, uint thumbPos, HWND hWndCtl);

void EvVScroll(uint scrollCode, uint thumbPos, HWND hWndCtl);

virtual int GetPosition() const;

virtual void GetRange(int& min, int& max) const;

virtual void SBBottom();

virtual void SBLineDown();

virtual void SBLineUp();

virtual void SBPageDown();

virtual void SBPageUp();

virtual void SBThumbPosition(int thumbPos);

virtual void SBThumbTrack(int thumbPos);

virtual void SBTop();

virtual void SetPosition(int thumbPos);

virtual void SetRange(int min, int max);

uint Transfer(void* buffer, TTransferDirection direction);

Protected Member Functions

char far* GetClassName();

void SetupWindow();

Response Table Entries

EV_ macros and member functions


TScrollBar::LineMagnitude

See Also	TScrollBar

Syntax

int LineMagnitude;

Description

The number of range units to scroll the scroll bar when the user requests a small movement by clicking on the scroll bar's arrows. TScrollBar's constructor sets LineMagnitude to 1 by default. (The scroll range is 0-100 by default.)


See Also

TScrollBar::SetupWindow


TScrollBar::PageMagnitude

TScrollBar

Syntax

int PageMagnitude;

Description

The number of range units to scroll the scroll bar when the user requests a large movement by clicking in the scroll bar's scrolling area. TScrollBar's constructor sets PageMagnitude to 10 by default. (The scroll range is 0-100 by default.)


TScrollBar Public Constructors

TScrollBar

Syntax 1

TScrollBar(TWindow* parent, int id, int x, int y, int w, int h, bool isHScrollBar, TModule* module = 0);

Description

Constructs and initializes a TScrollBar object with the given parent window (parent), a control ID (id), a position (x, y), and a width and height (w, h). Invokes the TControl constructor with similar parameters. If isHScrollBar is true, the constructor adds SBS_HORZ to the window style. If it is false, the constructor adds SBS_VERT. If the supplied height for a horizontal scroll bar or the supplied width for a vertical scroll bar is 0, a standard value is used. LineMagnitude is initialized to 1 and PageMagnitude is set to 10.

Syntax 2

TScrollBar(TWindow* parent,int resourceId,TModule* module = 0);

Description

Constructs a TScrollBar object to be associated with a scroll bar control of a TDialog object. Invokes the TControl constructor with identical parameters.

The resourceId parameter must correspond to a scroll bar resource that you define.


TScrollBar::DeltaPos

See Also	TScrollBar

Syntax

virtual int DeltaPos(int delta);

Description

Calls SetPosition to change the scroll bar's thumb position by the value supplied in delta. A positive delta moves the thumb down or right. A negative delta value moves the thumb up or left. DeltaPos returns the new thumb position.


See Also

TScrollBar::SetPosition


TScrollBar::EvHScroll

TScrollBar

Syntax

void EvHScroll(uint scrollCode, uint thumbPos, HWND hWndCtl);

Description

Response table handler that calls the virtual function (SBBottom, SBLineDown and so on) in response to messages sent by TWindow::DispatchScroll.


TScrollBar::EvVScroll

TScrollBar

Syntax

void EvVScroll(uint scrollCode, uint thumbPos, HWND hWndCtl);

Description

Response table handler that calls the virtual function (SBBottom, SBLineDown and so on) in response to messages sent by TWindow::DispatchScroll.


TScrollBar::GetPosition

See Also	TScrollBar

Syntax

virtual int GetPosition() const;

Description

Returns the scroll bar's current thumb position.


See Also

TScrollBar::SetPosition

TScrollBarData struct


TScrollBar::GetRange

See Also	TScrollBar

Syntax

virtual void GetRange(int& min, int& max) const;

Description

Returns the end values of the present range of scroll bar thumb positions in min and max.


See Also

TScrollBar::SetPosition

TScrollBar::SetRange

TScrollBarData struct


TScrollBar::SBBottom

TScrollBar

Syntax

virtual void SBBottom();

Description

Calls SetPosition to move the thumb to the bottom or right of the scroll bar. SBBottom is called to respond to the thumb's being dragged to the bottom or rightmost position of the scroll bar.


TScrollBar::SBLineDown

TScrollBar

Syntax

virtual void SBLineDown();

Description

Calls SetPosition to move the thumb down or right (by LineMagnitude units). SBLineDown is called to respond to a click on the bottom or right arrow of the scroll bar.


TScrollBar::SBLineUp

TScrollBar

Syntax

virtual void SBLineUp();

Description

Calls SetPosition to move the thumb up or left (by LineMagnitude units). SBLineUp is called to respond to a click on the top or left arrow of the scroll bar.


TScrollBar::SBPageDown

TScrollBar

Syntax

virtual void SBPageDown();

Description

Calls SetPosition to move the thumb down or right (by PageMagnitude units). SBPageDown is called to respond to a click in the bottom or right scrolling area of the scroll bar.


TScrollBar::SBPageUp

TScrollBar

Syntax

virtual void SBPageUp();

Description

Calls SetPosition to move the thumb up or left (by PageMagnitude units). SBPageUp is called to respond to a click in the top or left scrolling area of the scroll bar.


TScrollBar::SBThumbPosition

TScrollBar

Syntax

virtual void SBThumbPosition(int thumbPos);

Description

Calls SetPosition to move the thumb. SBThumbPosition is called to respond when the thumb is set to a new position.


TScrollBar::SBThumbTrack

TScrollBar

Syntax

virtual void SBThumbTrack(int thumbPos);

Description

Calls SetPosition to move the thumb as it is being dragged to a new position.


TScrollBar::SBTop

TScrollBar

Syntax

virtual void SBTop();

Description

Calls SetPosition to move the thumb to the top or right of the scroll bar. SBTop is called to respond to the thumb's being dragged to the top or rightmost position on the scroll bar.


TScrollBar::SetPosition

See Also	TScrollBar

Syntax

virtual void SetPosition(int thumbPos);

Description

Moves the thumb to the position specified in thumbPos. If thumbPos is outside the present range of the scroll bar, the thumb is moved to the closest position within range.


See Also

TScrollBar::GetPosition


TScrollBar::SetRange

See Also	TScrollBar

Syntax

virtual void SetRange(int min, int max);

Description

Sets the scroll bar to the range between min and max.


See Also

TScrollBar::GetRange


TScrollBar::Transfer

TScrollBar

Syntax

uint Transfer(void* buffer, TTransferDirection direction);

Description

Transfers scroll-bar data to or from the transfer buffer pointed to by buffer, which is expected to point to a TScrollBarData structure.

Data is transferred to or from the transfer buffer if tdGetData or tdSetData is supplied as the direction.

Transfer always returns the size of the transfer data (the size of the TScrollBarData structure). To retrieve the size of this data without transferring data, pass tdSizeData as the direction.


TScrollBar::GetClassName

TScrollBar

Syntax

char far* GetClassName();

Description

Returns the name of TScrollBar's registration class, "SCROLLBAR".


TScrollBar::SetupWindow

TScrollBar

Syntax

void SetupWindow();

Description

Sets the scroll bar's range to 0, 100. To redefine this range, call SetRange.


TScrollBar Response Table Entries

TScrollBar

Response table entry	Member function

EV_WM_HSCROLL	EvHScroll

EV_WM_VSCROLL	EvVScroll


TScrollBarData struct

See Also	TScrollBar	OWL Hierarchy	Inheritance

Header File

scrollba.h

Description

The TScrollBarData structure contains integer values that represent a range of thumb positions on the scroll bar. TScrollBar's function GetRange calls TScrollBarData to obtain the highest and lowest thumb positions on the scroll bar. GetPosition calls TScrollBarData to obtain the current thumb position on the scroll bar.

Public data members

int HighValue;

int LowValue;

int Position;


See Also

TScrollBar::Transfer


TScrollBar::TScrollBarData::HighValue
TScrollBarData::HighValue

See Also	TScrollBar

Syntax

int HighValue;

Description

Contains the highest value of the thumb position in the scroll bar's range.


See Also

TScrollBar::GetRange


TScrollBar::TScrollBarData::LowValue
TScrollBarData::LowValue

See Also	TScrollBar

Syntax

int LowValue;

Description

Contains the lowest value of thumb position in the scroll bar's range.


See Also

TScrollBar::GetRange


TScrollBar::TScrollBarData::Position
TScrollBarData::Position

See Also	TScrollBar

Syntax

int Position;

Description

Contains the scroll bar's thumb position.


See Also

TScrollBar::GetPosition


TScroller Class

OWL Hierarchy	Inheritance

Header File

scroller.h

Description

TScroller supports an automatic window-scrolling mechanism (referred to as autoscrolling) that works in conjunction with horizontal or vertical window scroll bars (it also works if there are no scroll bars). When autoscrolling is activated, the window automatically scrolls when the mouse is dragged from inside the client area of the window to outside that area. If the AutoMode data member is true, TScroller performs autoscrolling.

To use TScroller, set the Scroller member of your TWindow descendant to a TScroller object instantiated in the constructor of your TWindow descendant. TScroller is a streamable class.

Public Data Members

bool AutoMode;

bool AutoOrg;

bool HasHScrollBar, HasVScrollBar;

bool TrackMode;

TWindow* Window;

int XLine, YLine;

int XPage, YPage;

long XPos, YPos;

long XRange, YRange;

int XUnit, YUnit;

Public Constructor and Destructor

TScroller(TWindow* window, int xUnit, int yUnit, long xRange, long yRange);

virtual ~TScroller();

Public Member Functions

virtual void AutoScroll();

virtual void BeginView(TDC& dc, TRect& rect);

virtual void EndView();

virtual void HScroll(uint scrollEvent, int thumbPos);

virtual bool IsAutoMode();

bool IsVisibleRect(long x, long y, int xExt, int yExt);

virtual void SetPageSize();

virtual void SetRange(long xRange, long yRange);

virtual void SetSBarRange();

virtual void SetUnits(int xUnit, int yUnit);

void ScrollBy(long dx, long dy);

virtual void ScrollTo(long x, long y);

void SetWindow(TWindow* win);

virtual void VScroll(uint scrollEvent, int thumbPos);

int XScrollValue(long rangeUnit);

int XRangeValue(int scrollUnit);

int YScrollValue(long rangeUnit);

int YRangeValue(int scrollUnit);


TScroller::AutoMode

TScroller

Syntax

bool AutoMode;

Description

Is true if automatic scrolling is activated.


TScroller::AutoOrg

TScroller

Syntax

bool AutoOrg;

Description

Is true if scroller offsets original.


TScroller::HasHScrollBar, HasVScrollBar

TScroller

Syntax

bool HasHScrollBar, HasVScrollBar;

Description

Is true if scroller has horizontal or vertical scroll.


TScroller::TrackMode

TScroller

Syntax

bool TrackMode;

Description

Is true if track scrolling is activated.


TScroller::Window

TScroller

Syntax

TWindow* Window;

Description

Points to the window whose client area scroller is to be managed.


TScroller::XLine, YLine

TScroller

Syntax

int XLine, YLine;

Description

Specifies the number of logical device units per line to scroll the rectangle in the horizontal (X) and vertical (Y) directions.


TScroller::XPage, YPage

TScroller

Syntax

int XPage, YPage;

Description

Specifies the number of logical device units per page to scroll the rectangle in the horizontal (X) and vertical (Y) directions.


TScroller::XPos,YPos

TScroller

Syntax

long XPos, YPos;

Description

Specifies the current position of the rectangle in horizontal (XPos) and vertical (YPos) scroll units.


TScroller::XRange, YRange

TScroller

Syntax

long XRange, YRange;

Description

Specifies the number of horizontal and vertical scroll units.


TScroller::XUnit, YUnit

TScroller

Syntax

int XUnit, YUnit;

Description

Specifies the amount (in logical device units) to scroll the rectangle in the horizontal (X) and vertical (Y) directions. The rectangle is scrolled right if XUnit is positive and left if XUnit is negative. The rectangle is scrolled down if YUnit is positive and up if YUnit is negative.


TScroller Public Constructor and Destructor

TScroller

Syntax

TScroller(TWindow* window, int xUnit, int yUnit, long xRange, long yRange);

Description

Constructs a TScroller object with window as the owner window, and xUnit, yUnit, xRange, and yRange as xUnit, yUnit, xRange and yRange, respectively. Initializes data members to default values. HasHScrollBar and HasVScrollBar are set according to the scroll bar attributes of the owner window.

Destructor

virtual ~TScroller();

Description

Destructs a TScroller object. Sets owning window's Scroller number variable to 0.


TScroller::AutoScroll

TScroller

Syntax

virtual void AutoScroll();

Description

Scrolls the owner window's display in response to the mouse being dragged from inside to outside the window. The direction and the amount by which the display is scrolled depend on the current position of the mouse.


TScroller::BeginView

TScroller

Syntax

virtual void BeginView(TDC& dc, TRect& rect);

Description

If TScroller_AutoOrg is true (default condition), BeginView automatically offsets the origin of the logical coordinates of the client area by XPos, YPos during a paint operation. If AutoOrg is false (for example, when the scroller is larger than 32,767 units), you must set the offset manually.


TScroller::EndView

TScroller

Syntax

virtual void EndView();

Description

Updates the position of the owner window's scroll bars to be coordinated with the position of the TScroller.


TScroller::HScroll

TScroller

Syntax

virtual void HScroll(uint scrollEvent, int thumbPos);

Description

Responds to the specified horizontal scrollEvent by calling ScrollBy or ScrollTo. The type of scroll event is identified by the corresponding SB_ constants. thumbPos contains the current thumb position when the scroller is notified of SB_THUMBTRACK and SB_THUMBPOSITION scroll events.


TScroller::IsAutoMode

See Also	TScroller

Syntax

virtual bool IsAutoMode();

Description

IsAutoMode is true if automatic scrolling is activated.


See Also

TScroller::AutoMode


TScroller::IsVisibleRect

TScroller

Syntax

bool IsVisibleRect(long x, long y, int xExt, int yExt);

Description

Is true if the rectangle (x, y, xExt, and yExt) is visible.


TScroller::SetPageSize

See Also	TScroller

Syntax

virtual void SetPageSize();

Description

Sets the XPage and YPage data members to the width and height (in XUnits and YUnits) of the owner window's client area.


See Also

TScroller::XPage, YPage

TScroller::XUnit, YUnit


TScroller::SetRange

See Also	TScroller

Syntax

virtual void SetRange(long xRange, long yRange);

Description

Sets the xRange and yRange of the TScroller to the parameters specified. Then calls SetSBarRange to synchronize the range of the owner window's scroll bars.


See Also

TScroller::SetSBarRange


TScroller::SetSBarRange

TScroller

Syntax

virtual void SetSBarRange();

Description

Sets the range of the owner window's scroll bars to match the range of the TScroller.


TScroller::SetUnits

See Also	TScroller

Syntax

virtual void SetUnits(int xUnit, int yUnit);

Description

Sets the XUnit and YUnit data members to TheXUnit and TheYUnit, respectively. Updates XPage and YPage by calling SetPageSize.


See Also

TScroller::XPage, YPage

TScroller::XUnit, YUnit


TScroller::ScrollBy

TScroller

Syntax

void ScrollBy(long dx, long dy);

Description

Scrolls to a position calculated using the passed delta values (dx and dy). A positive delta position moves the thumb position down or right. A negative delta position moves the thumb up or left.


TScroller::ScrollTo

TScroller

Syntax

virtual void ScrollTo(long x, long y);

Description

Scrolls the rectangle to the position specified in x and y.


TScroller::SetWindow

TScroller

Syntax

void SetWindow(TWindow* win);

Description

Sets the owning window to win.


TScroller::VScroll

See Also	TScroller

Syntax

virtual void VScroll(uint scrollEvent, int thumbPos);

Description

Responds to the specified vertical scrollEvent by calling ScrollBy or ScrollTo. The type of scroll event is identified by the corresponding SB_ constants. thumbPos contains the current thumb position when the scroller is notified of SB_THUMBTRACK and SB_THUMBPOSITION scroll events.


See Also

TScroller::ScrollTo


TScroller::XScrollValue

See Also	TScroller

Syntax

int XScrollValue(long rangeUnit);

Description

XScrollValue converts a horizontal range value from the scroll bar to a horizontal scroll value.


See Also

TScroller::YScrollValue


TScroller::XRangeValue

See Also	TScroller

Syntax

int XRangeValue(int scrollUnit);

Description

XRangeValue converts a horizontal scroll value from the scroll bar to a horizontal range value.


See Also

TScroller::YRangeValue


TScroller::YScrollValue

See Also	TScroller

Syntax

int YScrollValue(long rangeUnit);

Description

YScrollValue converts a vertical range value from the scroll bar to a vertical scroll value.


See Also

TScroller::XScrollValue


TScroller::YRangeValue

See Also	TScroller

Syntax

int YRangeValue(int scrollUnit);

Description

YRangeValue converts a vertical scroll value from the scroll bar to a vertical range value.


See Also

TScroller::XRangeValue


 TSeparatorGadget Class

See Also	OWL Hierarchy	Inheritance

Header File

gadget.h

Description

TSeparatorGadget is a simple class you can use to create a separator between gadgets. To do so, you must specify the size of the separator in units of SM_CXBORDER (width of the window frame) and SM_CYBORDER (height of the window frame). Determines the width and height of the gadget and sets the right and bottom boundaries of the separator. By default, the separator disables itself and turns off shrink-wrapping. Note that the default border style is none.

Public Member Function

TSeparatorGadget(int size = 6);


See Also

TGadget::TBorderStyle enum


TSeparatorGadget::TSeparatorGadget

TSeparatorGadget

Syntax

TSeparatorGadget(int size = 6);

Description

Used for both the width and the height of the separator, size is initialized at 6 border units (the width or height of a thin window border).


TSize class

OWL Hierarchy

Header File

geometry.h

Description

TSize is a mathematical class derived from the structure tagSIZE.

The tagSIZE  struct is defined as

struct tagSIZE {

   int cx;

   int cy;

};

TSize encapsulates the notion of a two-dimensional quantity that usually represents a displacement or the height and width of a rectangle. TSize inherits the two data members cx and cy from tagSIZE. Member functions and operators are provided for comparing, assigning, and manipulating sizes. Overloaded << and >> operators allow chained insertion and extraction of TSize objects with streams.

Public Constructors

TSize();

TSize(int dx, int dy);

TSize(const POINT& point);

TSize(const SIZE& size);

TSize(uint32 dw);

Public Member Functions

int Magnitude() const;

TSize operator +(const TSize& size) const;

TSize operator -(const TSize& size) const;

TSize operator -() const;

bool operator ==(const TSize& other) const;

bool operator !=(const TSize& other) const;

TSize& operator +=(const TSize& size);

TSize& operator -=(const TSize& size);

ipstream& operator >>(ipstream& is, TSize& s);

opstream& operator <<(opstream& os, const TSize& s);

ostream& operator <<ostream& os, const TSize& s);


TSize Public Constructors

See Also	TSize

Syntax 1

TSize();

Description

The default TSize constructor.

Syntax 2

TSize(int dx, int dy);

Description

Creates a TSize object with cx = dx and cy = dy.

Syntax 3

TSize(const POINT& point);

Description

Creates a TSize object with cx = point.x and cy = point.y.

Syntax 4

TSize(const SIZE& size);

Description

Creates a TSize object with cx = size.cx and cy = size.cy.

Syntax 5

TSize(uint32 dw);

Creates a TSize object with cx = LOWORD(dw) and cy = HIWORD(dw)).


See Also

TPoint


TSize::Magnitude

TSize

Syntax

int Magnitude() const;

Description

Returns the length of the diagonal of the rectangle represented by this object. The value returned is an int approximation to the square root of (cx2 + cy2).


TSize::operator +

See Also	TSize

Syntax

TSize operator +(const TSize& size) const;

Description

Calculates an offset to this TSize object using the given size argument as the displacement. Returns the object (cx + size.cx, cy + size.cy). This TSize object is not changed.


See Also

TSize::operator -


TSize::operator -

See Also	TSize

Syntax 1

TSize operator -(const TSize& size) const;

Description

Calculates a negative offset to this TSize object using the given size argument as the displacement. Returns the point (cx - size.cx, cy - size.cy). This object is not changed.

Syntax 2

TSize operator -() const;

Description

Returns the TSize object (-cx, -cy). This object is not changed.


See Also

TSize::operator +


TSize::operator ==

See Also	TSize

Syntax

bool operator ==(const TSize& other) const;

Description

Returns true if this TSize object is equal to the other TSize object; otherwise returns false.


See Also

TSize::operator !=


TSize::operator !=

See Also	TSize

Syntax

bool operator !=(const TSize& other) const;

Description

Returns false if this TSize object is equal to the other TSize object; otherwise returns true.


See Also

TSize::operator ==


TSize::operator +=

See Also	TSize

Syntax

TSize& operator +=(const TSize& size);

Description

Offsets this TSize object by the given size argument. This TSize object is changed to (cx + size.cx, cy + size.cy). Returns a reference to this object.


See Also

TSize::operator -=


TSize::operator -=

See Also	TSize

Syntax

TSize& operator -=(const TSize& size);

Description

Negatively offsets this TSize object by the given size argument. This object is changed to (cx - size.cx, cy - size.cy). Returns a reference to this object.


See Also

TSize::operator +=


TSize::operator >>

See Also	TSize

Syntax

ipstream& operator >>(ipstream& is, TSize& s);

Description

Extracts a TSize object from is, the given input stream, and copies it to s. Returns a reference to the resulting stream, allowing the usual chaining of >> operations.


See Also

TSize operator <<


TSize::operator <<

See Also	TSize

Syntax 1

opstream& operator <<(opstream& os, const TSize& s);

Description

Inserts the given TSize object s into the opstream os. Returns a reference to the resulting stream, allowing the usual chaining of << operations.

Syntax 2

ostream& operator <<(ostream& os, const TSize& s);

Description

Formats and inserts the given TSize object s into the ostream os. The format is "(cx x cy)". Returns a reference to the resulting stream, allowing the usual chaining of << operations.


See Also

TSize operator >>


TSlider Class

See Also	Hierarchy	Inheritance

Header File

slider.h

Description

An abstract base class derived from TScrollBar, TSlider defines the basic behavior of sliders (controls that are used for providing nonscrolling, position information). Like scroll bars, sliders have minimum and maximum positions as well as line and page magnitude. Sliders can be moved using either the mouse or the keyboard. If you use a mouse to move the slider, you can drag the thumb position, click on the slot on either side of the thumb position to move the thumb by a specified amount (PageMagnitude), or click on the ruler to position the thumb at a specific spot on the slider. The keyboard's Home and End keys move the thumb position to the minimum (Min) and maximum (Max) positions on the slider.

 You can use TSlider 's member functions to cause the thumb positions to automatically align with the nearest tick positions. (This is referred to as snapping.) You can also specify the tick gaps (the space between the lines that separate the major divisions of the X- or Y-axis).

The sample program SLIDER.CPP on your distribution disk displays the following thermostat that uses sliders:

Sample Thermostat that Uses Sliders

Public Constructor and Destructor

TSlider(TWindow* parent, int id, int X, int Y, int W, int H, TResId thumbResId, TModule* module = 0);

~TSlider();

Public Member Functions

int GetPosition() const;

void GetRange(int &min, int &max) const;

void SetPosition(int thumbPos);

void SetRange(int min, int max);

void SetRuler(int ticGap, bool snap = false);

Protected Member Functions

bool EvEraseBkgnd(HDC hDC);

uint EvGetDlgCode(MSG far* msg);

void EvKeyDown(uint key, uint repeatCount, uint flags);

void EvKillFocus(HWND hWndGetFocus);

void EvLButtonDblClk(uint modKeys, TPoint& point);

void EvLButtonDown(uint modKeys, TPoint& point);

void EvLButtonUp(uint modKeys, TPoint& point);

void EvMouseMove(uint modKeys, TPoint& point);

void EvPaint();

void EvSetFocus(HWND hWndLostFocus);

void EvSize(uint sizeType, TSize& size);

void GetBkColor(TDC& dc);

virtual int HitTest(TPoint& point) = 0;

virtual void NotifyParent(int scrollCode, int pos=0) = 0;

virtual void PaintRuler(TDC& dc) = 0;

virtual void PaintSlot(TDC& dc) = 0;

virtual void PaintThumb(TDC& dc);

virtual int PointToPos(TPoint& point) = 0;

virtual TPoint PosToPoint(int pos) = 0;

virtual void SetupThumbRgn();

void SetupWindow();

virtual void SlideThumb(TDC& dc, int thumbPos);

int SnapPos(int pos);

Protected Data Members

TColor BkColor;

TRect CaretRect;

int Max;

int Min;

static TSize MouseOffset;

int Pos;

uint Range;

static TDC* SlideDC;

bool Sliding;

int SlotThick;

bool Snap;

TRect ThumbRect;

TResId ThumbResId;

TRegion* ThumbRgn;

int TicGap;

Response Table Entries

EV_ macros and member functions


See Also

TVSlider

THSlider


Sample Thermostat that Uses Sliders


TSlider Public Constructor and Destructor

TSlider

Syntax

TSlider(TWindow* parent, int id, int X, int Y, int W, int H, TResId thumbResId, TModule* module = 0);

Description

Constructs a slider object setting Pos and ThumbRgn to 0, TicGap to Range divided by 10, SlotThick to 17, Snap to true, and Sliding to false. Sets Attr.W and Attr.H to the values in X and Y. ThumbResId is set to thumbResId.

Destructor

~TSlider();

Description

Destructs a TSlider object and deletes ThumbRgn.


TSlider::GetPosition

See Also	TSlider

Syntax

int GetPosition() const;

Description

Returns the slider's current thumb position. Overloads TScrollBar's virtual function.


See Also

TSlider::SetPosition


TSlider::GetRange

See Also	TSlider

Syntax

void GetRange(int &min, int &max) const;

Description

Returns the end values of the present range of slider thumb positions in min and max. Overloads TScrollBar's virtual function.


See Also

TSlider::SetRange


TSlider::SetPosition

See Also	TSlider

Syntax

void SetPosition(int thumbPos);

Description

Moves the thumb to the position specified in thumbPos. If thumbPos is outside the present range of the slider, the thumb is moved to the closest position within the specified range. Overloads TScrollBar's virtual function.


See Also

TSlider::GetPosition


TSlider::SetRange

See Also	TSlider

Syntax

void SetRange(int min, int max);

Description

Sets the slider to the range between min and max. Overloads TScrollBar's virtual function.


See Also

TSlider::GetRange


TSlider::SetRuler

TSlider

Syntax

void SetRuler(int ticGap, bool snap = false);

Description

Sets the slider's ruler. Each slider has a built-in ruler that is drawn with the slider. The ruler, which can be blank or have tick marks on it, can be created so that it forces the thumb to snap to the tick positions automatically.


TSlider::EvEraseBkgnd

See Also	TSlider

Syntax

bool EvEraseBkgnd(HDC hDC);

Description

Responds to a WM_ERASEBKGND message and erases the background of the slider when the slider is changed. Calls the virtual functions PaintRuler, PaintSlot, and PaintThumb to paint the components of the slider. To avoid flickering, EvEraseBkgnd is called to erase the background as the painting occurs.


See Also

TSlider::EvPaint


TSlider::EvGetDlgCode

See Also	TSlider

Syntax

uint EvGetDlgCode(MSG far* msg);

Description

Responds to a WM_GETDLGCODE message and let the dialog manager control the response to a DIRECTION key or TAB key input. Captures cursor-movement keys to move the thumb by returning a DLGC_WANTARROWS message, which indicates that direction keys are desired.The msg parameter indicates the kind of message (for example, a control or a command message) sent to the dialog box manager.

EvGetDlgCode returns a code that indicates how the control message is to be treated.


See Also

TButton::EvGetDlgCode

TWindow::DefaultProcessing

DLGC_xxxxdialogcontrolmessageconstants


TSlider::EvKeyDown

TSlider

Syntax

void EvKeyDown(uint key, uint repeatCount, uint flags);

Description

Translates the virtual key code into a movement and then moves the thumb. key indicates the virtual key code of the pressed key, repeatCount holds the number of times the same key is pressed, and flags contains one of the following messages, which translate to virtual key (VK) codes:

Value	Virtual key code

SB_PAGEUP	VK_PRIOR

SB_PAGEDOWN	VK_NEXT

SB_BOTTOM	VK_END

SB_TOP	VK_HOME

SB_LINEUP	VK_LEFT(same as SB_LINELEFT)

SB_LINEUP	VK_UP

SB_LINEDOWN	VK_RIGHT(same as SB_LINERIGHT)

SB_LINEDOWN	VK_DOWN


TSlider::EvKillFocus

TSlider

Syntax

void EvKillFocus(HWND hWndGetFocus);

Description

In response to a WM_KILLFOCUS message sent to a window that is losing the keyboard, EvKillFocus hides and then destroys the caret.


TSlider::EvLButtonDblClk

TSlider

Syntax

void EvLButtonDblClk(uint modKeys, TPoint& point);

Description

Responds to a WM_LBUTTONDBLCLK message (which indicates the user double-clicked the left mouse button), then throws away the messages so the base class does not receive them.


TSlider::EvLButtonDown

See Also	TSlider

Syntax

void EvLButtonDown(uint modKeys, TPoint& point);

Description

Responds to a mouse press by positioning the thumb or beginning a mouse drag. If the mouse is pressed down while it is over the thumb, EvLButtonDown enters sliding state. If the mouse is in the slot, EvLButtonDown pages up or down. If the mouse is on the ruler, EvLButtonDown jumps to that position. EvLButtonDown generates a scroll code of SB_THUMBPOSITION, SB_LINEUP, SB_LINEDOWN, SB_PAGEUP, SB_PAGEDOWN, or SB_THUMBTRACK.


See Also

TSlider::EvLButtonUp


TSlider::EvLButtonUp

See Also	TSlider

Syntax

void EvLButtonUp(uint modKeys, TPoint& point);

Description

If the mouse button is released, EvLButtonUp ends sliding, paging, or jumping to a position on the ruler.


See Also

TSlider::EvLButtonDown


TSlider::EvMouseMove

TSlider

Syntax

void EvMouseMove(uint modKeys, TPoint& point);

Description

Moves the mouse to the indicated position. If the mouse is being dragged, EvMouseMove positions the thumb and sends the appropriate message to the parent window.


TSlider::EvPaint

See Also	TSlider

Syntax

void EvPaint();

Description

Paints the entire slider--ruler, slot, and thumb. Calls the virtual functions PaintRuler, PaintSlot, and PaintThumb to paint the components of the slider.


See Also

TSlider::EvEraseBkgnd


TSlider::EvSetFocus

TSlider

Syntax

void EvSetFocus(HWND hWndLostFocus);

Description

Creates a blinking caret to show the focus in the current window.


TSlider::EvSize

TSlider

Syntax

void EvSize(uint sizeType, TSize& size);

Description

Recalculates the size of the slider when the window size is changed.


TSlider::GetBkColor

TSlider

Syntax

void GetBkColor(TDC& dc);

Description

Sends a WM_CTLCOLOR message to the parent and calls dc::GetBkColor to extract the background color for the slider.


TSlider::HitTest

See Also	TSlider

Syntax

virtual int HitTest(TPoint& point) = 0;

Description

Gets information about where a given X,Y location falls on the slider. The return value is in scrollCodes. Each of the derived classes performs comparisons to return a scroll code.


See Also

TSlider::NotifyParent


TSlider::NotifyParent

See Also	TSlider

Syntax

virtual void NotifyParent(int scrollCode, int pos=0) = 0;

Description

Sends a WS_HSCROLL or WS_VSCROLL message to the parent window.


See Also

TVSlider::HitTest


TSlider::PaintRuler

TSlider

Syntax

virtual void PaintRuler(TDC& dc) = 0;

Description

Paints the ruler. It is assumed that the slot or thumb do not overlap the ruler.


TSlider::PaintSlot

TSlider

Syntax

virtual void PaintSlot(TDC& dc) = 0;

Description

Paints the slot in which the thumb slides.


TSlider::PaintThumb

TSlider

Syntax

virtual void PaintThumb(TDC& dc);

Description

Paints the thumb itself using a resource DIB that overlaps the slot and is translated to the current system button colors.


TSlider::PointToPos

See Also	TSlider

Syntax

virtual int PointToPos(TPoint& point) = 0;

Description

Translates an X,Y point to a position in slider units.


See Also

TSlider::PosToPoint


TSlider::PosToPoint

See Also	TSlider

Syntax

virtual TPoint PosToPoint(int pos) = 0;

Description

Translates a position in slider units to an X,Y point.


See Also

TSlider::PointToPos


TSlider::SetupThumbRgn

See Also	TSlider

Syntax

virtual void SetupThumbRgn();

Description

Creates the region that defines the thumb shape for this slider class. Although the default region is a simple bounding rectangle, it can be any shape. While the slider thumb is being moved, this region is used for testing the mouse position and updating the thumb position.


See Also

TSlider::ThumbRgn


TSlider::SetupWindow

TSlider

Syntax

void SetupWindow();

Description

Calls TScrollBar::SetupWindow and SetupThumbRgn to set up the window.


TSlider::SlideThumb

TSlider

Syntax

virtual void SlideThumb(TDC& dc, int thumbPos);

Description

Slides the thumb to a given position and performs the necessary blitting and painting.


TSlider::SnapPos

See Also	TSlider

Syntax

int SnapPos(int pos);

Description

Constrains pos so it is in the range from Min to Max and (if snapping is enabled) performs snapping by rounding pos to the nearest TicGap.


See Also

TSlider::TicGap


TSlider::Bkcolor

TSlider

Syntax

TColor BkColor;

Description

Stores the background color of the slider.


TSlider::CaretRect

TSlider

Syntax

TRect CaretRect;

Description

Refers to the position of the caret's rectangle.


TSlider::Max

TSlider

Syntax

int Max;

Description

Contains the maximum value of the slider position.


TSlider::Min

TSlider

Syntax

int Min;

Description

Contains the minimum value of the slider position.


TSlider::MouseOffset

TSlider

Syntax

static TSize MouseOffset;

Description

Shows the offset from the rectangle's original top left position to the position where the mouse is clicked. When the rectangle is moved, it can maintain a set relationship to the position of the mouse click.


TSlider::Pos

See Also	TSlider

Syntax

int Pos;

Description

Indicates where the thumb is positioned on the slider.


See Also

TSlider::GetPosition


TSlider::Range

TSlider

Syntax

uint Range;

Description

Contains the difference between the maximum and minimum range of the slider.


TSlider::SlideDC

TSlider

Syntax

static TDC* SlideDC;

Description

Used while the mouse is down and the thumb is sliding, SlideDC reflects the movement of the mouse on the DC.


TSlider::Sliding

TSlider

Syntax

bool Sliding;

Description

true if the thumb is sliding. Otherwise, false.


TSlider::SlotThick

TSlider

Syntax

int SlotThick;

Description

Indicates the thickness of the slot. Set to 17 by default.


TSlider::Snap

TSlider

Syntax

bool Snap;

Description

true if snapping is activated; otherwise false.


TSlider::ThumbRect

TSlider

Syntax

TRect ThumbRect;

Description

Holds the thumb's bounding rectangle.


TSlider::ThumbResId

TSlider

Syntax

TResId ThumbResId;

Description

The bitmap resource ID for the thumb knob.


TSlider::ThumbRgn

See Also	TSlider

Syntax

TRegion* ThumbRgn;

Description

Refers to the region, if any, that defines the thumb shape for this slider class.


See Also

TSlider::SetupThumbRgn


TSlider::TicGap

TSlider

Syntax

int TicGap;

Description

Specifies the amount of space in pixels between ticks.


TSlider Response Table Entries
TSlider::Response Table Entries

TSlider

Response table entry	Member function

EV_WM_ERASEBKGND	EvEraseBkgnd

EV_WM_GETDLGCODE	EvGetDlgCode

EV_WM_KEYDOWN	EvKeyDown

EV_WM_KILLFOCUS	EvKillFocus

EV_WM_LBUTTONDBLCLK	EvLButtonDblClk

EV_WM_LBUTTONDOWN	EvLButtonDown

EV_WM_LBUTTONUP	EvLButtonUp

EV_WM_MOUSEMOVE	EvMouseMove

EV_WM_PAINT	EvPaint

EV_WM_SETFOCUS	EvSetFocus

EV_WM_SIZE	EvSize


THSlider class

OWL Hierarchy	Inheritance

Header File

slider.h

Description

Derived from TSlider, THSlider provides implementation details for horizontal sliders.

The sample program SLIDER.CPP on your distribution disk displays the following thermostat that uses a horizontal slider:

Sample Thermostat that Uses Sliders

Public Constructors

THSlider(TWindow* parent, int id, int X, int Y, int W, int H, TResId thumbResId = IDB_HSLIDERTHUMB, TModule* module = 0);

Protected member functions

int HitTest(TPoint& point);

void NotifyParent(int scrollCode, int pos=0);

void PaintRuler(TDC&);

void PaintSlot(TDC&);

int PointToPos(TPoint& point);

TPoint PosToPoint(int pos);


THSlider Public constructors

THSlider

Constructor

THSlider(TWindow* parent, int id, int X, int Y, int W, int H, TResId thumbResId = IDB_HSLIDERTHUMB, TModule* module = 0);

Description

Constructs a slider object with a default bitmap resource ID of IDB_HSLIDERTHUMB for the thumb knob.


THSlider::HitTest

THSlider

Syntax

int HitTest(TPoint& point);

Description

Overrides TSlider's virtual HitTest function and gets information about where a given X,Y location falls on the slider. The return value is in scrollCodes.


THSlider::NotifyParent

THSlider

Syntax

void NotifyParent(int scrollCode, int pos=0);

Description

Overrides TSlider's virtual NotifyParentfunction and sends a WS_HSCROLL message to the parent window.


THSlider::PaintRuler

THSlider

Syntax

void PaintRuler(TDC&);

Description

Overrides TSlider's virtual PaintRulerfunction and paints the horizontal ruler.


THSlider::PaintSlot

THSlider

Syntax

void PaintSlot(TDC&);

Description

Overrides TSlider's virtual PaintSlotfunction and paints the slot in which the thumb slides.


THSlider::PointToPos

THSlider

Syntax

int PointToPos(TPoint& point);

Description

Overrides TSlider's virtual PointToPosfunction and translates an X,Y point to a position in slider units.


THSlider::PosToPoint

THSlider

Syntax

TPoint PosToPoint(int pos);

Description

Overrides TSlider's virtual PosToPointfunction and translates a position in slider units to an X,Y point.


TVSlider Class

OWL Hierarchy	Inheritance

Header File

slider.h

Description

Derived from TSlider, TVSlider provides implementation details for vertical sliders. See TSlider for an illustration of a vertical slider.

Public Constructor

TVSlider(TWindow* parent, int id, int X, int Y, int W, int H, TResId thumbResId = IDB_VSLIDERTHUMB, TModule* module = 0);

Protected Member Functions

int HitTest(TPoint& point);

void NotifyParent(int scrollCode, int pos=0);

void PaintRuler(TDC& dc);

void PaintSlot(TDC& dc);

int PointToPos(TPoint& point);

TPoint PosToPoint(int pos);


TVSlider::Public Constructor
TVSlider Public Constructor

TVSlider

Syntax

TVSlider(TWindow* parent, int id, int X, int Y, int W, int H, TResId thumbResId = IDB_VSLIDERTHUMB, TModule* module = 0);

Description

Constructs a vertical slider object with a default bitmap resource ID of IDB_VSLIDERTHUMB for the thumb knob.


TVSlider::HitTest

See Also	TVSlider

Syntax

int HitTest(TPoint& point);

Description

Overrides TSlider's virtual function and gets information about where a given X, Y location falls on the slider. The return value is in scrollCodes.


See Also

TSlider::HitTest


TVSlider::NotifyParent

See Also	TVSlider

Syntax

void NotifyParent(int scrollCode, int pos=0);

Description

Overrides TSlider's virtual function and sends a WS_VSCROLL message to the parent window.


See Also

TSlider::NotifyParent


TVSlider::PaintRuler

See Also	TVSlider

Syntax

void PaintRuler(TDC& dc);

Description

Overrides TSlider's virtual function and paints the vertical ruler.


See Also

TSlider::PaintRuler


TVSlider::PaintSlot

See Also	TVSlider

Syntax

void PaintSlot(TDC& dc);

Description

Overrides TSlider's virtual function and paints the slot in which the thumb slides.


See Also

TSlider::PaintSlot


TVSlider::PointToPos

See Also	TVSlider

Syntax

int PointToPos(TPoint& point);

Description

Overrides TSlider's virtual function and translates an X,Y point to a position in slider units.


See Also

TSlider::PointToPos


TVSlider::PosToPoint

See Also	TVSlider

Syntax

TPoint PosToPoint(int pos);

Description

Overrides TSlider's virtual function and translates a position in slider units to an X,Y point.


See Also

TSlider::PosToPoint


TSortedStringArray Class

OWL Hierarchy	See Also

Header File

validate.h

Description

Implements a list of ASCII characters stored as a sorted array of elements that are string objects. TSortedStringArray can perform many of the string manipulation functions, such as adding and removing elements from the array, and provides many of the common C++ functions implemented by container classes.

Public Constructors

TSortedStringArray(int upper, int lower, int delta);

Type Definitions

typedef void (*IterFunc)(string&, void*);

typedef int (*CondFunc)(const string&, void*);

Public Member Functions

int Add(const string& t);

unsigned ArraySize() const;

int Destroy(const string& t);

int Destroy(int loc);

int Detach(const string& t);

int Detach(int loc);

int Find(const string& t) const;

string* FirstThat(CondFunc cond, void* args) const;

void Flush();

void ForEach(IterFunc iter, void* args);

unsigned GetItemsInContainer() const;

int HasMember(const string& t) const;

int IsEmpty() const;

int IsFull() const

string* LastThat(CondFunc cond, void* args) const;

int LowerBound() const;

string& [](int loc);

string& [](int loc) const;

int UpperBound() const;


See Also

TValidator

TLookupValidator


TSortedStringArray::TSortedStringArray
TSortedStringArray Public Constructor

Syntax

TSortedStringArray(int upper, int lower, int delta);

Description

Constructs a TSortedStringArray object with an upper boundary of upper, a lower boundary of lower, and a growth delta of delta.


TSortedStringArray::void

Syntax

typedef void (*IterFunc)(string&, void*);

Definition

Function type used as a parameter to the ForEach member function.


TSortedStringArray::int

Syntax

typedef int (*CondFunc)(const string&, void*);

Description

Function type used as a parameter to the FirstThat and LastThat member functions.


TSortedStringArray::Add

Syntax

int Add(const string& t);

Description

Adds an element to the array at the next available index position. Adding an element beyond the upper boundary leads to an overflow condition. If this condition occurs and the growth delta, delta, (from the constructor) is nonzero, the array is expanded (by sufficient multiples of delta bytes) to accommodate the addition. If delta is zero, Add fails. Add returns 0 if the object could not be added.


TSortedStringArray::ArraySize

Syntax

unsigned ArraySize() const;

Description

Returns the size of the array.


TSortedStringArray::Destroy

Form 1

int Destroy(const string& t);

Form 2

int Destroy(int loc);

Description

Form 1: Removes the element specified by t and deletes it.

Form 2: Removes an element from the array at the specified index location, loc, and deletes it.


TSortedStringArray::Detach

Form 1

int Detach(const string& t);

Form 2

int Detach(int loc);

Description

Form 1: Removes the specified element from the array. Returns 1 if successful; otherwise, returns 0.

Form 2: Removes an element from the array at the specified index location, loc. Returns 1 if successful; otherwise, returns 0.


TSortedStringArray::Find

Syntax

int Find(const string& t) const;

Description

Finds the first element represented by t and returns the index where the element is located.


TSortedStringArray::FirstThat

Syntax

string* FirstThat(CondFunc cond, void* args) const;

Description

Returns a pointer to the first element in the array that satisfies a specified condition. cond is the test function pointer that returns true for a specified condition. args contains the various arguments passed. Returns 0 if no element in the array satisfies the given condition. Because FirstThat creates its own internal iterator, you can use it as a search function also.


TSortedStringArray::Flush

Syntax

void Flush();

Description

Removes all elements from the array without destroying the array itself.


TSortedStringArray::ForEach

Syntax

void ForEach(IterFunc iter, void* args);

Description

Creates an internal iterator to execute the specified function, iter, for each element in the array. Use the args argument to pass various kinds of data to this function.


TSortedStringArray::GetItemsInContainer

Syntax

unsigned GetItemsInContainer() const;

Description

Returns the number of elements in the array.


TSortedStringArray::HasMember

Syntax

int HasMember(const string& t) const;

Description

Returns 1 if the element specified by t exists in the array; otherwise returns 0.


TSortedStringArray::IsEmpty

Syntax

int IsEmpty() const;

Description

Returns 1 if the array is empty; otherwise, returns 0.


TSortedStringArray::IsFull

Syntax

int IsFull() const

Description

Returns 1 if the array is full; otherwise, returns 0.


TSortedStringArray::LastThat

Syntax

string* LastThat(CondFunc cond, void* args) const;

Description

Returns a pointer to the last element in the array that satisfies a specified condition. cond is the test function pointer that returns true for a specified condition. args contains the various arguments passed. Returns 0 if no element in the array satisfies the given condition. Because LastThat creates its own internal iterator, you can use it as a search function also.


TSortedStringArray::LowerBound

Syntax

int LowerBound() const;

Description

Returns the array's lower boundary.


TSortedStringArray::UpperBound

Syntax

int UpperBound() const;

Description

Returns the array's upper boundary.


TSortedStringArray::operator [ ]

Form 1

string& operator [](int loc);

Form 2

string& operator [](int loc) const;

Description

Form 1: Returns a reference to the element at the location specified by loc. This version resizes the array if it is necessary to make loc a valid index.

Form 2: Returns a reference to the element at the location specified by loc. This version throws an exception in the debugging version on an attempt to index out of bounds.


 TStatic class

OWL Hierarchy

Header File

static.h

Description

An interface object that represents a static text interface element. Static elements consist of text or graphics that the user does not change. An application, however, can modify the static control. You must use a TStatic object, for example, to create a static control that's used to display a text label such as a copyright notice in a parent TWindow object. TStatic can also be used to make it easier to modify the text of static controls in TDialog objects. See the sample program in the EXAMPLES\OWL\OWLAPI\STATIC directory for an example of a static control.

Public Data Members

uint TextLen;

Public Constructors

TStatic(TWindow* parent, int id, const char far* title, int x, int y, int w, int h, uint textLen = 0, TModule* module = 0);

TStatic(TWindow* parent, int resourceId, uint textLen = 0, TModule* module = 0);

Public Member Functions

virtual void Clear();

int GetText(char far* str, int maxChars);

int GetTextLen();

void SetText(const char far* str);

uint Transfer(void* buffer, TTransferDirection direction);

Protected Member Functions

void EvSize(uint sizeType, TSize& size);

virtual char far* GetClassName();

Response Table Entries

EV_ macros and member functions


TStatic::TextLen

TStatic

Syntax

uint TextLen;

Description

Holds the size of the text buffer for static controls.  Because of the null terminator on the string, the number of characters that can be stored in the static control is one less than TextLen. TextLen is also the number of bytes transferred by the Transfer member function.


TStatic Public Constructors

TStatic

Syntax 1

TStatic(TWindow* parent, int id, const char far* title, int x, int y, int w, int h, uint textLen = 0, TModule* module = 0);

Description

Constructs a static control object with the supplied parent window (parent), control ID (Id), text (title), position (x, y) relative to the origin of the parent window's client area, width (w), height (h), and default text length (textLen) of zero. By default, the static control is visible upon creation and has left-justified text. (Set to WS_CHILD | WS_VISIBLE | WS_GROUP | SS_LEFT.) Invokes a TControl constructor. You can change the default style of the static control via the control object's constructor.

Syntax 2

TStatic(TWindow* parent, int resourceId, uint textLen = 0, TModule* module = 0);

Description

Constructs a TStatic object to be associated with a static control interface control of a TDialog object. Invokes the TControl constructor with similar parameters, then sets TextLen to textLen. Disables the data transfer mechanism by calling DisableTransfer. The resourceId parameter must correspond to a static control resource that you define.


TStatic::Clear

TStatic

Syntax

virtual void Clear();

Description

Clears the text of the associated static control.


TStatic::EvSize

TStatic

Syntax

void EvSize (uint sizeType, TSize& size);

Description

Overrides TWindow's virtual EvSize function. When the static control is resized, EvSize ensures that it is repainted.


TStatic::GetText

TStatic

Syntax

int GetText(char far* str, int maxChars);

Description

Retrieves the static control's text, stores it in the str argument of maxChars size, and returns the number of characters copied.


TStatic::GetTextLen

TStatic

Syntax

int GetTextLen();

Description

Returns the length of the static control's text.


TStatic::SetText

TStatic

Syntax

void SetText(const char far* str);

Description

Sets the static control's text to the string supplied in str.


TStatic::Transfer

TStatic

Syntax

uint Transfer(void* buffer, TTransferDirection direction);

Description

Transfers TextLen characters of text to or from a transfer buffer pointed to by buffer. If direction is tdGetData, the text is transferred to the buffer from the static control. If direction is tdSetData, the static control's text is set to the text contained in the transfer buffer. Transfer returns TextLen, the number of bytes stored in or retrieved from the buffer. If direction is tdSizeData, Transfer returns TextLen without transferring data.


TStatic::GetClassName

TStatic

Syntax

virtual char far* GetClassName();

Description

Returns the name of TStatic's registration class (STATIC), or returns STATIC_CLASS if Borland Windows Custom Controls (BWCC) is enabled.


TStatic::Response Table Entries

TStatic

Response table entry	Member function

EV_WM_SIZE	EvSize


TStatus Class

OWL Hierarchy

Header File

except.h

Description

Used primarily for backward compatibility with previous versions of ObjectWindows, TStatus is used by TModule and TWindow to indicate an error in the initialization of an interface object. If Status is set to a nonzero value, a TXCompatibility exception is thrown.

Public Constructor

TStatus();

Public Data Members

TStatus& operator =(int statusCode)

operator int() const;


TStatus Public Constructor

See Also	TStatus

Syntax

TStatus();

Description

Constructs a TStatus object and initializes the status code to 0.


See Also

TModule::Status

TWindow::Status


TStatus::operator =

TStatus

Syntax

TStatus& operator =(int statusCode);

Description

Sets the status code and throws a TXCompatibility exception.


TStatus::operator int

Syntax

operator int() const;

Description

Returns the status code.


TStatusBar Class

OWL Hierarchy	Inheritance

Header File

statusba.h

Description

TStatusBar provides support for status bars, inserted gadgets, hint text, and keyboard modes. In contrast to plain message bars, status bars provide several display options. ObjectWindows status bars let you include multiple text gadgets (the text on the left of the status bar) and different border styles. You can also reserve space for mode indicators (the text that displays the program's current state, such as extended selection (of keys and other modes), CapsLock, NumLock, ScrollLock, Overtype, and macro recording). By default, ObjectWindows uses these virtual key codes and displays the following strings for the indicated enabled modes:

Mode	Virtual key code	Text displayed

Extended	EXT

CapsLock	VK_CAPITAL	CAPS

NumLock	VK_NUMLOCK	NUM

ScrollLock	VK_SCROLL	SCRL

Overtype	VK_INSERT	OVR

Macro recording	REC

TStatusBar creates text gadgets for the mode indicators you request and adjusts the spacing between mode indicators. The TSpacing struct stores spacing and layout unit constraints.

Like other control bars, the status bar is constructed and destroyed at the same time as its parent's window, but this is not a required procedure.

The following program statements show how to construct a status bar and insert it at the bottom of the window.

TStatusBar* sb = new TStatusBar(0, TGadget_Recessed,
   TStatusBar_CapsLock | TStatusBar_NumLock | TStatusBar_Overtype);

frame->Insert(*sb, TDecoratedFrame::Bottom);

MainWindow = frame;

See the MDIFILE.CPP sample program on your distribution disk for an example of how to create a window with a status bar.

Type Definitions

enum TModeIndicator {ExtendSelection = 1, CapsLock = 1 << 1, NumLock = 1 << 2, ScrollLock = 1 << 3, Overtype = 1 << 4, RecordingMacro = 1 << 5};

Public Constructors

TStatusBar(TWindow* parent = 0, TGadget::TBorderStyle borderStyle = TGadget::Recessed, uint modeIndicators = 0, TFont *font = new TGadgetWindowFont, TModule* module = 0);

Public Member Functions

bool GetModeIndicator(TModeIndicator i) const;

void Insert(TGadget& gadget, TPlacement = After, TGadget* sibling = 0);

TGadget* operator[](uint index);

void SetModeIndicator(TModeIndicator, bool state);

void SetSpacing(TSpacing& spacing);

void ToggleModeIndicator(TModeIndicator);

Protected Data Members

TGadget::TBorderStyle BorderStyle;

uint ModeIndicators;

uint ModeIndicatorState;

uint NumModeIndicators;

TSpacing Spacing;

Protected Member Functions

bool IdleAction(long);

void PositionGadget(TGadget* previous, TGadget* next, TPoint& point);

bool PreProcessMsg(MSG& msg);


TStatusBar::TModeIndicator enum

TStatusBar

Syntax

enum TModeIndicator {ExtendSelection = 1, CapsLock = 1 << 1, NumLock = 1 << 2, ScrollLock = 1 << 3, Overtype = 1 << 4, RecordingMacro = 1 << 5};

Description

Enumerates the keyboard modes. By default, these are arranged horizontally on the status bar from left to right. Sets the extended selection, CapsLock, NumLock, ScrollLock, Overtype, and recording macro indicators.


TStatusBar Public Constructor

TStatusBar

Syntax

TStatusBar(TWindow* parent = 0, TGadget_TBorderStyle borderStyle = TGadget_Recessed, uint modeIndicators = 0, TFont* font = new TGadgetWindowFont, TModule* module = 0);

Description

Constructs a TStatusBar object in the parent window and creates any new gadgets and mode indicator gadgets. Sets BorderStyle to borderStyle, ModeIndicators to modeIndicators, and NumModeIndicators to 0. borderStyle can be any one of the values of the BorderStyle enum (for example, Plain, Raised, Recessed, or Embossed). The parameter mode indicators can be one of the values of the TModeIndicator enum, such as CapsLock, NumLock, ScrollLock, or Overtype. The parameter font points to a font object that contains the type of fonts used for the gadget window. The parameter, module, which defaults to 0, is passed to the base TWindow's constructor in the module parameter. Sets the values of the margins and borders depending on whether the gadget is raised, recessed, or plain.


TStatusBar::GetModeIndicator

TStatusBar

Syntax

bool GetModeIndicator(TModeIndicator i) const;

Description

Returns the current status bar mode indicator.


TStatusBar::Insert

TStatusBar

Syntax

void Insert(TGadget& gadget, TPlacement = After, TGadget* sibling = 0);

Description

Inserts the gadget (objects derived from class TGadget) in the status bar. By default, the new gadget is placed just after any existing gadgets and to the left of the status mode indicators. For example, you can insert a painting tool or a happy face that activates a recorded macro.


TStatusBar::operator [ ]

TStatusBar

Syntax

TGadget* operator[](uint index);

Description

Returns a gadget at a given index, but cannot access mode indicator gadgets.


TStatusBar::SetModeIndicator

See Also	TStatusBar

Syntax

void SetModeIndicator(TModeIndicator, bool state);

Description

Sets TModeIndicator to a given text gadget and set the status (on, by default) of the mode indicator. For the mode indicator to appear on the status bar, you must specify the mode when the window is constructed.


See Also

TStatusBar::TModeIndicator


TStatusBar::ToggleModeIndicator

TStatusBar

Syntax

void ToggleModeIndicator(TModeIndicator);

Description

Toggles the ModeIndicator.


TStatusBar::SetSpacing

See Also	TStatusBar

Syntax

void SetSpacing(TSpacing& spacing);

Description

Uses the TSpacing values to set the spacing to be used between mode indicator gadgets. TSpacing sets the status-bar margins in layout units. Typically, the message indicator (the leftmost text gadget) is left-justified on the status bar and the other indicators are right-justified. See TLayoutMetrics for a detailed explanation of layout units and constraints.

struct TSpacing {

    TMargins::TUnits  Units;

    int Value;

    TSpacing() {Units = TMargins::LayoutUnits; Value = 0;}

};


See Also

TStatusBar::TModeIndicator


TStatusBar::BorderStyle

TStatusBar

Syntax

TGadget::TBorderStyle BorderStyle;

Description

One of the enumerated border styles--None, Plain, Raised, Recessed, or Embossed--used by the mode indicators on the status bar.


TStatusBar::ModeIndicators

TStatusBar

Syntax

uint ModeIndicators;

Description

The ModeIndicators bit field indicates which mode indicators have been created for the status bar.


TStatusBar::NumModeIndicators

TStatusBar

Syntax

uint NumModeIndicators;

Description

Specifies the number of mode indicators, which can range from 1 to 5.


TStatusBar::ModeIndicatorState

TStatusBar

Syntax

uint ModeIndicatorState;

Description

Specifies the mode of the status bar. This can be any one of the values of TModeIndicator enum, such as CapsLock, NumLock, ScrollLock, Overtype, RecordingMacro, or ExtendSelection.


TStatusBar::Spacing

TStatusBar

Syntax

TSpacing Spacing;

Description

Specifies the spacing between mode indicators on the status bar.


TStatusBar::IdleAction

See Also	TStatusBar

Syntax

bool IdleAction(long);

Description

If more than one application is running, TStatusBar calls IdleAction instead of PreProcessMsg to check the state of the NumLock, CapsLock, or ScrollLock keys and to update the mode indicators if they do not reflect the current status of these keys.


See Also

TStatusBar::PreProcessMsg


TStatusBar::PositionGadget

TStatusBar

Syntax

void PositionGadget(TGadget* previous, TGadget* next, TPoint& point);

Description

Determines the position of the new gadget in relation to any previously existing gadgets and uses the Pixels, LayoutUnits, and BorderUnits fields of TMargins to determine the amount of spacing to leave between the mode indicators.


TStatusBar::PreProcessMsg

See Also	TStatusBar

Syntax

bool PreProcessMsg(MSG& msg);

Description

Overrides TWindow::PreProcessMsg to process keyboard messages and update the mode indicators when the NumLock, CapsLock, or ScrollLock keys are pressed.


See Also

TStatusBar::IdleAction


TStorageDocument Class

OWL Hierarchy	Inheritance

Header File

stgdoc.h

Description

Derived from TDocument, TStorageDocument supplies functionality that supports OLE's compound file structure. A compound file structure is a file-management system that stores files in a hierarchical structure within a root file. This storage structure is analagous to the directory or folder and file scheme used on a disk, except that a directory is called a storage and a file is called a stream.

In addition, TStorageDocument provides support for OLE's compound document mechanism. A compound document can store many different kinds of embedded objects, for example, spreadsheets as well as bitmaps.

Basically, TStorageDocument supports having a document read and write its own storage. In order to provide this functionality, TStorageDocument overrides several virtual methods from TDocument and, following TDocument's strategy, also applies property lists both to documents and to their views. In this way, documents can use these attributes to read files in from storage and write files out to storage

Messages are sent to the application, which queries the properties in order to determine how to process the document or view. Each derived class must implement its own property attribute types  - either string or binary data.

Type Definitions

enum TStgDocProp{PrevProperty, CreateTime, ModifyTime, AccessTime,StorageSize, IStorageInstance, NextProperty};

Public Constructors and Destructors

TStorageDocument(TDocument* parent = 0): TDocument(parent), StorageI(0), OpenCount(0), CanRelease(false);

~TStorageDocument();

Public Member Functions

bool Close();

bool Commit(bool force = false);

bool CommitTransactedStorage();

int FindProperty(const char far* name);

int GetProperty(int index, void far* dest, int textlen=0);

IStorage* GetStorage();

TInStream* InStream(int omode, const char far* strmId=0);

bool IsOpen();

bool Open(int omode, const char far* name);

virtual bool OpenHandle(int omode, HANDLE hGlobal);

TOutStream* OutStream(int omode, const char far* strmId=0);

int PropertyCount();

int PropertyFlags(int index);

const char* PropertyName(int index);

virtual bool ReleaseDoc();

bool Revert(bool clear = false);

bool SetDocPath(const char far* path);

bool SetProperty(int index, const void far* src);

IStorage* SetStorage(IStorage* stg);

Protected Data Members

int ThisOpen;

IStorage* StorageI;


See Also

TDocument

TOleDocument


TStorageDocument::TStgDocProp enum

TStorageDocument

Syntax

enum TStgDocProp {PrevProperty, CreateTime, ModifyTime, AccessTime, StorageSize, IStorageInstance, NextProperty};

Description

Enumerates the following constants that define the document's properties:

Constant	Meaning

PrevProperty 	Should always have a value of TDocument::NextProperty - 1. This is the initial value in any document's property list.

CreateTime	The time the file is created.

ModifyTime	The time the file is modified.

AccessTime	The last time the file was accessed.

StorageSize	The size of the storage buffer.

IStorageInstance	The storage instance for the document.

NextProperty	The final value for any document's list of properties.


TStorageDocument Public Constructor and Destructor

TStorageDocument

Constructor syntax

TStorageDocument(TDocument* parent = 0): TDocument(parent), StorageI(0), OpenCount(0), CanRelease(false);

Description

Constructs a TStorageDocument object with the specified TDocument  parent window. Sets the data members StorageI and OpenCount to 0. Sets CanRelease to false. Later, the member function ReleaseDoc sets this flag to true so that the document can be closed.

Destructor syntax

~TStorageDocument();

Description

Destroys a TStorageDocument object.


TStorageDocument::InStream

See Also	TStorageDocument

Syntax

TInStream* InStream(int omode, const char far* strmId=0);

Description

Provides an input stream for the TStorageDocument object. Returns a pointer to a TInStream object. The parameter omode contains a combination of the document open and sharing modes (for example, ofReadWrite) defined in docview.h. The strmId  parameter is used for documents that support named streams.


See Also

TStorageDocument::OutStream

TInStream

ofxxxx Document Open Enum


TStorageDocument::OutStream

See Also	TStorageDocument

Syntax

TOutStream* OutStream(int omode, const char far* strmId=0);

Description

Provides an output stream for a particular storage medium. Returns a pointer to a TOutSteam. The parameter omode contains a combination of the document open and sharing modes (for example, ofReadWrite ) defined in docview.h. The strmId  parameter is used for documents that support named streams.


See Also

TStorageDocument::InStream

TOutStream

ofxxxx Document Open Enum


TStorageDocument::Open

See Also	TStorageDocument

Syntax

bool Open(int omode, const char far* name);

Description

Opens or creates a document based on IStorage. The name parameter specifies the name of the document, if any, to open. The omode parameter contains a combination of the document open and sharing modes (for example, ofReadWrite) defined in docview.h.


See Also

TStorageDocument::Close

TOutStream

ofxxxx Document Open Enum

TOleDocument::Open


TStorageDocument::Close

See Also	TStorageDocument

Syntax

bool Close();

Description

Releases the IStorage if CanRelease is true. (CanRelease  is set to true when ReleaseDoc is called.) Before closing the document, Close checks any child documents and tries to close them.


See Also

TStorageDocument::Open

TStorageDocument::ReleaseDoc

TOutStream

ofxxxx Document Open Enum


TStorageDocument::Commit

TStorageDocument

Syntax

bool Commit(bool force = false);

Description

Saves the current data to storage. When a file is closed, the document manager calls either Commit or Revert. If force is true, all data is written to storage. TDocument's Commit checks any child documents and commits their changes to storage also. Before the current data is saved, all child documents must return  true. If all child documents return  true, Commit flushes the views for any operations that occurred since the last time the view was checked. Once all data for the document object is updated and saved, Commit returns true.


TStorageDocument::CommitTransactedStorage

TStorageDocument

Syntax

bool CommitTransactedStorage();

Description

If a file is opened or created in transacted mode, call CommitTransactedStorage to commit a document to permanent storage. By default, a document uses transacted instead of direct storage. With transacted storage, a document written to IStorage is only temporary until it is committed permanently. If a compound file is opened or created in direct mode, then CommitTransactedStorage does not need to be called.


TStorageDocument::Revert

TStorageDocument

Syntax

bool Revert(bool clear = false);

Description

Performs the reverse of Commit and cancels any changes made to the storage document since the last commit. If clear is true, data is not reloaded for views. Revert also checks all child documents and cancels any changes if all children return true. When a file is closed, the document manager calls either Commit or Revert. Revert returns true if the revert operation is successful.


TStorageDocument::SetDocPath

TStorageDocument

Syntax

bool SetDocPath(const char far* path);

Description

Sets the document path for the Open and Save file operations.


TStorageDocument::IsOpen

TStorageDocument

Syntax

bool IsOpen();

Description

Checks to see if the storage document has any IStorage created. If there is no storage, IsOpen returns false; otherwise, it returns true.


TStorageDocument::FindProperty

See Also	TStorageDocument

Syntax

int FindProperty(const char far* name);

Description

Gets the property index, given the property name. Returns the integer index number that corresponds to the name. If the name isn't found in the list of properties, returns 0.


See Also

pfxxxx property attribute constants


TStorageDocument::PropertyFlags

See Also	TStorageDocument

Syntax

int PropertyFlags(int index);

Description

Returns the attributes of a specified property given the index of the property whose attributes you want to retrieve.


See Also

pfxxxx property attribute constants


TStorageDocument::PropertyName

See Also	TStorageDocument

Syntax

const char* PropertyName(int index);

Description

Returns the name of the property given the index value.


See Also

pfxxxx property attribute constants


TStorageDocument::PropertyCount

See Also	TStorageDocument

Syntax

int PropertyCount();

Description

Gets the total number of properties for the TStorageDocument object. Returns NextProperty - 1.


See Also

pfxxxx property attribute constants


TStorageDocument::GetProperty

See Also	TStorageDocument

Syntax

int GetProperty(int index, void far* dest, int textlen=0);

Description

Returns the total number of properties for this storage document, where index is the property index, dest contains the property data, and textlen is the size of the property array. If textlen is 0, the property data is returned as binary data; otherwise, the property data is returned as text data.


See Also

pfxxxx property attribute constants

TStorageDocument::SetProperty


TStorageDocument::SetProperty

See Also	TStorageDocument

Syntax

bool SetProperty(int index, const void far* src);

Description

Sets the value of the property, given the index of the property, and src, the data type (either binary or text) to which the property must be set.


See Also

pfxxxx property attribute constants

TStorageDocument::GetProperty


TStorageDocument::OpenHandle

See Also	TStorageDocument

Syntax

virtual bool OpenHandle(int omode, HANDLE hGlobal);

Description

 OpenHandle writes data to a memory block. OpenHandle first creates an ILockBytes interface on the global handle and then creates an IStorage based on the ILockBytes interface. The parameter omode contains a combination of the document open and sharing modes (for example, ofReadWrite) defined in docview.h.


See Also

ofxxxx Document Open Enum


ILockBytes

An OLE 2 interface that implements reading, writing, and locking a series of bytes in a file.


TStorageDocument::GetStorage

See Also	TStorageDocument

Syntax

IStorage* GetStorage();

Description

Returns the document's root IStorage.


See Also

TStorageDocument::SetStorage


TStorageDocument::ThisOpen

See Also	TStorageDocument

Syntax

int ThisOpen;

Description

Holds the actual mode bits used for opening the storage. The mode bits determine how the file is opened: for example, read only, read and write, and so on.


See also

ofxxxx Document Open Enum


TStorageDocument::ReleaseDoc

TStorageDocument

Syntax

virtual bool ReleaseDoc();

Description

Releases the storage for the document and closes the document.


TStorageDocument::StorageI

See Also	TStorageDocument

Syntax

IStorage* StorageI;

Description

Holds the current IStorage instance. (If no storage is open, StorageI is 0.)


See also

TStorageDocument::GetStorage

TStorageDocument::SetStorage


TStorageDocument::SetStorage

See Also	TStorageDocument

Syntax

IStorage* SetStorage(IStorage* stg);

Description

Attaches an IStorage pointer (stg) to this document.


See also

TStorageDocument::GetStorage

TStorageDocument::StorageI


TStream Class

OWL Hierarchy

Header File

docview.h

Description

An abstract base class, TStream provides links between streams and documents, views, and document files.

Public Destructor

~TStream();

Public Member Functions

TDocument& GetDocument();

int GetOpenMode();

const char far* GetStreamName();

Protected Data Members

TDocument& Doc;

TStream* NextStream;

Protected Constructor

TStream(TDocument& doc, const char far* name,int mode);


TStream Public Destructor

TStream

Destructor

~TStream();

Description

Closes the stream. Derived classes generally close the document if it was opened especially for this stream.


TStream::GetDocument

TStream

Syntax

TDocument& GetDocument();

Description

Returns the current document that is open for streaming.


TStream::GetOpenMode

See Also	TStream

Syntax

int GetOpenMode();

Description

Gets mode flags used when opening document streams. For example, the stream can be opened in ofRead mode to allow reading, but not changing (writing to) the file.


See Also

ofxxxx document open enum


TStream::GetStreamName

TStream

Syntax

const char far* GetStreamName();

Description

Gets the name of the stream used for opening the document.


TStream::Doc

TStream

Syntax

TDocument& Doc;

Description

Stores the document that owns this stream.


TStream::NextStream

TStream

Syntax

TStream* NextStream;

Description

Points to the next stream in the list of active streams.


TStream Protected Constructor

See Also	TStream

Syntax

TStream(TDocument& doc, const char far* name,int mode);

Description

Constructs a TStream object. The doc parameter refers to the document object, name is the user-defined name of the stream, and mode is the mode used for opening the stream.


See Also

TInStream

TOutStream

ofXXXX document open enum

shXXXX document sharing enum


TStringLookupValidator::TStringLookupValidator Class
 TStringLookupValidator Class

OWL Hierarchy	Inheritance

Header File

validate.h

Description

Derived from TLookupValidator, TStringLookupValidator is a streamable class. A TStringLookupValidator object verifies the data in its associated edit control by searching through a collection of valid strings. You can use string-lookup validators when your edit control needs to accept only members of a certain set of strings.

Public Constructor and Destructor

TStringLookupValidator(TSortedStringArray* strings);

~TStringLookupValidator();

Public Member Functions

void Error();

bool Lookup(const char far* str);

void NewStringList(TSortedStringArray* strings);

Protected Data Member

TSortedStringArray* Strings;


TStringLookupValidator Public Constructor and Destructor
TStringLookupValidator Public Constructors and Destructor

TStringLookupValidator

Syntax

TStringLookupValidator(TSortedStringArray* strings);

Destructor

~TStringLookupValidator();

Description

Constructs a string-lookup object by first calling the constructor inherited from TLookupValidator and then setting Strings to strings.

Destructor

This destructor disposes of a list of valid strings by calling NewStringList and then disposes of the string-lookup validator object by calling the Destructor inherited from TLookupValidator.


TStringLookupValidator::Error

See Also	TStringLookupValidator

Syntax

void Error();

Description

Overrides TValidator's virtual function and displays a message box indicating that the typed string does not match an entry in the string list.


See Also

TValidator::Error


TStringLookupValidator::Lookup

See Also	TStringLookupValidator

Syntax

bool Lookup(const char far* str);

Description

Overrides TLookupValidator's virtual function. Returns true if the string passed in str matches any of the strings. Uses the search method of the string collection to determine if str is present.


See Also

TLookupValidator::Lookup


TStringLookupValidator::NewStringList

TStringLookupValidator

Syntax

void NewStringList(TSortedStringArray* strings);

Description

Sets the list of valid input string for the string-lookup validator. Disposes of any existing string list and then sets Strings to strings.


TStringLookupValidator::Strings

TStringLookupValidator

Syntax

TSortedStringArray* Strings;

Description

Points to a string collection containing all the valid strings the user can type. If Strings is NULL, all input is validated.


TSystemMenu::TSystemMenu Class
TSystemMenu Class

OWL Hierarchy	Inheritance

Header File

menu.h

Description

TSystemMenu creates a system menu object that then becomes the existing system menu.

Public Constructor

TSystemMenu(HWND wnd, bool revert = false);


TSystemMenu::Public Constructor
TSystemMenu Public constructors

See Also	TSystemMenu

Syntax

TSystemMenu(HWND wnd, bool revert = false);

Description

Constructs a system menu object. If revert is true, then the menu created is a default system menu. Otherwise, it is the menu currently in the window.


See Also

TPopupMenu::TPopupMenu


TTextGadget Class

OWL Hierarchy	Inheritance

Header File

textgadg.h

Description

Derived from TGadget, TTextGadget is a text gadget object. When you construct a text gadget, you must specify how many characters you want to reserve space for and how the text should be aligned horizontally. The inner boundaries of the text gadget are computed by multiplying the number of characters by the maximum character width.

Public Constructor and Destructor

TTextGadget(int id = 0, TBorderStyle = Recessed, TAlign = Left, uint numChars = 10, const char* text = 0);

~TTextGadget();

Public Member Functions

char* GetText();

void SetText(const char* text);

Protected Data Members

TAlign Align;

uint NumChars;

char* Text;

uint TextLen;

Protected Member Functions

void GetDesiredSize(TSize &size);

void Invalidate();

void Paint(TDC& dc);

Type Definition

enum TTileDirection;

enum TAlign {Left, Center, Right};


TTextGadget::TAlign

TTextGadget

Syntax

enum TAlign {Left, Center, Right};

Description

Enumerates the text-alignment attributes. Left aligns the text at the left edge of the bounding rectangle. Right aligns the text at the right edge of the bounding rectangle. Center aligns the text horizontally at the center of the bounding rectangle.


TTextGadget Public Constructor and Destructor

TTextGadget

Constructor

TTextGadget(int id = 0, TBorderStyle = Recessed, TAlign = Left, uint numChars = 10, const char* text = 0);

Destructor

~TTextGadget();

Description

Constructs a TTextGadget object with the specified ID, border style, and alignment. Sets Margins.Left and Margins.Right to 2. Sets Text and TextLen to 0.

Destructor

Destroys a TTextGadget object.


TTextGadget::GetText

TTextGadget

Syntax

char* GetText();

Description

Returns the text for the gadget.


TTextGadget::SetText

TTextGadget

Syntax

void SetText(const char* text);

Description

If the text stored in Text is not the same as the new text, SetText deletes the text stored in Text. Then, it sets TextLen to the length of the new string. If no text exists, it sets both Text and TextLen to 0 and then calls Invalidate to invalidate the rectangle.


TTextGadget::Align

TTextGadget

Syntax

TAlign Align;

Description

Text alignment attribute--left, center, or right-aligned.


TTextGadget::NumChars

TTextGadget

Syntax

uint NumChars;

Description

Holds the number of text characters.


TTextGadget::Text

TTextGadget

Syntax

char* Text;

Description

Points to the text for the gadget.


TTextGadget::TextLen

TTextGadget

Syntax

uint TextLen;

Description

Stores the length of the text.


TTextGadget::GetDesiredSize

See Also	TTextGadget

Syntax

void GetDesiredSize(TSize &size);

Description

If shrink-wrapping is requested, GetDesiredSize returns the size needed to accommodate the borders, margins, and text; otherwise, if shrink-wrapping is not requested, it returns the gadget's current width and height.


See Also

TGadget::GetDesiredSize


TTextGadget::Invalidate

See Also	TTextGadget

Syntax

void Invalidate();

Description

Calls TGadget::GetInnerRect to compute the area of the text for the gadget and then TGadget::InvalidateRect to invalidate the rectangle in the parent window.


See Also

TGadget::GetInnerRect

TGadget::Invalidate


TTextGadget::Paint

See Also	TTextGadget

Syntax

void Paint(TDC& dc);

Description

Calls TGadget::PaintBorder to paint the border. Calls TGadget::GetInnerRect to calculate the area of the text gadget's rectangle. If the text is left-aligned, Paint calls dc.GetTextExtent to compute the width and height of a line of the text. To set the background color, Paint calls dc.GetSysColor and sets the default background color to face shading (COLOR_BTNFACE). To set the button text color, Paint calls dc.SetTextColor and sets the default button text color to COLOR_BTNTEXT. To draw the text, Paint calls dc.ExtTextOut and passes the parameters ETO_CLIPPED (so the text is clipped to fit the rectangle) and ETO_OPAQUE (so the rectangle is filled with the current background color).


See Also

TGadget::Paint


TTileDirection enum

See Also	TTextGadget

Header file

gadgetwi.h

Syntax

enum TTileDirection{Horizontal, Vertical};

Description

Enumerates the two directions the gadget can be tiled. TGadgetWindow::TileGadgets actually tiles the gadgets in the direction requested.


See Also

TGadgetWindow::Direction

TGadgetWindow::TileGadgets


TTinyCaption Class

OWL Hierarchy	Inheritance

Header File

tinycapt.h

Description

Derived from TWindow, TTinyCaption is a mix-in class that handles a set of non-client events to produce a smaller caption bar for a window. Whenever it displays the caption bar, TTinyCaption checks the window style and handles the WS_SYSMENU, WS_MINIMIZEBOX, WS_MAXIMIZEBOX display attributes. Thus, you can use TTinyCaption to set the attributes of the tiny caption bar before enabling the caption. For example,

Attr.Style = WS_POPUP | WS_BORDER | WS_SYSMENU | WS_MINIMIZEBOX | WS_MAXIMIZEBOX;

TTinyCaption provides functions that let you manipulate frame types, border styles, and menus. You can adjust the height of the caption bar or accept the default height, which is about one-half the height of a standard caption bar. If you set CloseBox to true, then the window will close when you click the close box instead of displaying the system menu.

The sample program OWLCMD.CPP on your distribution disk displays the following tiny caption bar:

If you are using TTinyCaption as a mix-in class that does partial event handling, call the DoXxxx function in the mix-in class (instead of the EvXxxx function) to avoid duplicating default processing. The following example from OWLCMD.CPP (a sample program on your distribution disk) illustrates this process:

void TMyFrame::EvSysCommand(uint cmdType,TPoint& p)

{

if (TTinyCaption::DoSysCommand(cmdType, p) == esPartial)

FrameWindow::EvSysCommand(cmdType, p);

The TFLoatingFrame class can be used with TTinyCaption to produce a close box. See the sample programs OWLCMD.CPP and MDIFILE.CPP on your distribution disk for examples of how to use TTinyCaption.

Protected Data Members

TSize Border;

TFont* CaptionFont;

int CaptionHeight;

bool CloseBox;

uint DownHit;

TSize Frame;

bool IsPressed;

bool TCEnabled;

bool WaitingForSysCmd;

Protected Constructor and Destructor

TTinyCaption();

~TTinyCaption();

Protected Member Functions

TEventStatus DoCommand(uint id, HWND hWndCtl, uint notifyCode, LRESULT& evRes);

TEventStatus DoLButtonUp(uint hitTest, TPoint& screenPt);

TEventStatus DoMouseMove(uint hitTest, TPoint& screenPt);

TEventStatus DoNCActivate(bool active, bool& evRes);

TEventStatus DoNCCalcSize(bool calcValidRects, NCCALCSIZE_PARAMS far& calcSize, uint& evRes);

TEventStatus DoNCHitTest(TPoint& screenPt, uint& evRes);

TEventStatus DoNCLButtonDown(uint hitTest, TPoint& screenPt);

TEventStatus DoNCPaint();

TEventStatus DoSysCommand(uint cmdType, TPoint& p);

void DoSysMenu;

void EnableTinyCaption(int ch=58, bool closeBox=false);

LRESULT EvCommand(uint id, HWND hWndCtl, uint notifyCode);

void EvLButtonUp(uint hitTest, TPoint& screenPt);

void EvMouseMove(uint hitTest, TPoint& screenPt);

bool EvNCActivate(bool active);

uint EvNCCalcSize(bool calcValidRects, NCCALCSIZE_PARAMS far& calcSize);

uint EvNCHitTest(TPoint& screenPt);

void EvNCLButtonDown(uint hitTest, TPoint& screenPt);

void EvNCPaint();

void EvSysCommand(uint cmdType, TPoint& p);

TRect GetCaptionRect();

TRect GetMaxBoxRect();

TRect GetMinBoxRect();

TRect GetSysBoxRect();

void PaintButton(TDC& dc, TRect& boxRect, bool pressed);

void PaintCaption(bool active);

void PaintCloseBox(TDC& dc, TRect& boxRect, bool pressed);

void PaintMaxBox(TDC& dc, TRect& boxRect, bool pressed);

void PaintMinBox(TDC& dc, TRect& boxRect, bool pressed);

void PaintSysBox(TDC& dc, TRect& boxRect, bool pressed);

Response Table Entries

EV_ macros and member functions


TTinyCaption::Border

TTinyCaption

Syntax

TSize Border;

Description

Thin frame border size for dividers.


TTinyCaption::CaptionHeight

TTinyCaption

Syntax

int CaptionHeight;

Description

Height of the caption bar.


TTinyCaption::CaptionFont

TTinyCaption

Syntax

TFont* CaptionFont;

Description

Font used for the text in the tiny caption bar.


TTinyCaption::CloseBox

TTinyCaption

Syntax

bool CloseBox;

Description

If true, the window will close when the close box is clicked.


TTinyCaption::DownHit

TTinyCaption

Syntax

uint DownHit;

Description

Location of mouse-button press or cursor move.


TTinyCaption::Frame

TTinyCaption

Syntax

TSize Frame;

Description

Actual left and right, top and bottom dimensions of the caption bar.


TTinyCaption::IsPressed

TTinyCaption

Syntax

bool IsPressed;

Description

Is true if a mouse button is pressed.


TTinyCaption::TCEnabled

TTinyCaption

Syntax

bool TCEnabled;

Description

Is true if the tiny caption bar is displayed.


TTinyCaption::WaitingForSysCmd

TTinyCaption

Syntax

bool WaitingForSysCmd;

Description

Is true if TTinyCaption is ready to receive system messages.


TTinyCaption Protected Constructor and Destructor

TTinyCaption

Constructor

TTinyCaption();

Destructor

~TTinyCaption();

Description

Constructs a TTinyCaption object attached to the given parent window. Initializes the caption font to 0 and TCEnabled to false so that the tiny caption bar is not displayed automatically.

Destructor

Destroys a TTinyCaption object and deletes the caption font.


TTinyCaption::DoCommand

See Also	TTinyCaption

Syntax

TEventStatus DoCommand(uint id, HWND hWndCtl, uint notifyCode, LRESULT& evRes);

Description

Displays the system menu using ::TrackPopup so that TTinyCaption sends WM_COMMAND instead of WM_SYSCOMMAND messages. If a system menu command is received, it's then transformed into a WM_SYSCOMMAND message. If the tiny caption bar is false, DoCommand returns esPartial.


See Also

TTinyCaption::EvCommand

TEventStatus enum


TTinyCaption::DoLButtonUp

See Also	TTinyCaption

Syntax

TEventStatus DoLButtonUp(uint hitTest, TPoint& screenPt);

Description

Releases the mouse capture if the caption bar is enabled and a mouse button is pressed. Sets hitTest, indicating the mouse button has been pressed. Captures the mouse message and repaints the smaller buttons before returning esComplete.


See Also

TTinyCaption::EvLButtonUp


TTinyCaption::DoMouseMove

TTinyCaption

Syntax

TEventStatus DoMouseMove(uint hitTest, TPoint& screenPt);

Description

Returns TEventStatus.


TTinyCaption::DoNCActivate

See Also	TTinyCaption

Syntax

TEventStatus DoNCActivate(bool active, bool& evRes);

Description

If the tiny caption is not enabled or is iconic, returns esPartial. Otherwise, repaints the caption as an active caption and returns esComplete.


See Also

TTinyCaption::EvNCActivate


TTinyCaption::DoNCCalcSize

See Also	TTinyCaption

Syntax

TEventStatus DoNCCalcSize(bool calcValidRects, NCCALCSIZE_PARAMS far& calcSize, uint& evRes);

Description

If the caption bar is not enabled or is iconic, returns esPartial. Otherwise, calculates the dimensions of the caption and returns esComplete.


See Also

TTinyCaption::EvNCCalcSize


TTinyCaption::DoNCHitTest

See Also	TTinyCaption

Syntax

TEventStatus DoNCHitTest(TPoint& screenPt, uint& evRes);

Description

If the caption bar is not enabled, returns esPartial. Otherwise, sends a message to the caption bar that the mouse or the cursor has moved, and returns esComplete.


See Also

TTinyCaption::EvNCHitTest


TTinyCaption::DoNCLButtonDown

See Also	TTinyCaption

Syntax

TEventStatus DoNCLButtonDown(uint hitTest, TPoint& screenPt);

Description

If the caption bar is not enabled, returns esPartial. Otherwise, determines if the user released the button outside or inside a menu, and returns esComplete.


See Also

TTinyCaption::EvNCLButtonDown


TTinyCaption::DoNCPaint

See Also	TTinyCaption

Syntax

TEventStatus DoNCPaint();

Description

If the caption bar is not enabled or is iconized, returns esPartial. Otherwise, gets the focus, paints the caption, and returns esPartial, thus indicating that a separate paint function must be called to paint the borders of the caption.


See Also

TTinyCaption::EvNCPaint


TTinyCaption::DoSysCommand

See Also	TTinyCaption

Syntax

TEventStatus DoSysCommand(uint cmdType, TPoint& p);

Description

If the caption bar is not enabled, returns esPartial. If the caption bar is iconized and the user clicks the icon, calls DoSysMenu to display the menu in its normal mode and returns esComplete.


See Also

TTinyCaption::EvSysCommand


TTinyCaption::DoSysMenu

TTinyCaption

Syntax

void DoSysMenu;

Description

Gets the system menu and sets up menu items. DoSysMenu is also responsible for displaying and tracking the status of the menu.


TTinyCaption::EnableTinyCaption

TTinyCaption

Syntax

void EnableTinyCaption(int ch=58, bool closeBox=false);

Description

Activates the tiny caption bar. By default, EnableTinyCaption replaces the system window with a tiny caption window that does not close when the system window is clicked. If the closeBox argument is true, clicking on the system menu will close the window instead of bringing up the menu. You can use EnableTinyCaption to hide the window if you are using a tiny caption in a derived class. To diminish the tiny caption bar, try the following values:

EnableTinyCaption(30, true);

To maximize the tiny caption bar, use these values:

EnableTinyCaption(48, true);


TTinyCaption::EvCommand

See Also	TTinyCaption

Syntax

LRESULT EvCommand(uint id, HWND hWndCtl, uint notifyCode);

Description

EvCommand provides extra processing for commands, but lets the focus window and its parent windows handle the command first.


See Also

TTinyCaption::DoCommand


TTinyCaption::EvLButtonUp

TTinyCaption

Syntax

void EvLButtonUp(uint hitTest, TPoint& screenPt);

Description

Responds to a mouse button-up message by calling DoLButtonUp. If DoLButtonUp does not return IsComplete, EvLButtonUp calls TWindow::EvLButtonUp.


TTinyCaption::EvMouseMove

TTinyCaption

Syntax

void EvMouseMove(uint hitTest, TPoint& screenPt);

Description

Responds to a mouse-move message by calling DoMouseMove. If DoMouseMove does not return IsComplete, EvMouseMove calls TWindow::EvMouseMove.


TTinyCaption::EvNCActivate

TTinyCaption

Syntax

bool EvNCActivate(bool active);

Description

Responds to a request to change a title bar or icon by calling DoNCActivate. If DoNCActivate does not return esComplete, EvNCActivate calls TWindow::EvNCActivate.


TTinyCaption::EvNCCalcSize

TTinyCaption

Syntax

uint EvNCCalcSize(bool calcValidRects, NCCALCSIZE_PARAMS far& calcSize);

Description

Responds to a request to change a title bar or icon by calling DoNCActivate. If DoNCActivate does not return esComplete, EvNCActivate calls TWindow::EvNCActivate.

Calculates the size of the command window including the caption and border so that it can fit within the window.


TTinyCaption::EvNCHitTest

TTinyCaption

Syntax

uint EvNCHitTest(TPoint& screenPt);

Description

Responds to a cursor move or press of a mouse button by calling DoNCHitTest. If DoNCHitTest does not return esComplete, EvNCHitTest calls TWindow::EvNCHitTest.


TTinyCaption::EvNCLButtonDown

TTinyCaption

Syntax

void EvNCLButtonDown(uint hitTest, TPoint& screenPt);

Description

Responds to a press of the left mouse button while the cursor is within the nonclient area of the caption bar by calling DoNCLButtonDown. If DoNCLButtonDown does not return esComplete, EvNCLButtonDown calls TWindow::EvNCLButtonDown.


TTinyCaption::EvNCPaint

See Also	TTinyCaption

Syntax

void EvNCPaint();

Description

Responds to a request to change a title bar or icon. Paints the indicated device context or display screen and does any special painting required for the caption.


See Also

TTinyCaption::DoNCActivate


TTinyCaption::EvSysCommand

TTinyCaption

Syntax

void EvSysCommand(uint cmdType, TPoint& p);

Description

Responds to a WM_SYSCOMMAND message by calling DoSysCommand. If DoSysCommand returns esPartial, EvSysCommand calls TWindow::EvSysCommand.


TTinyCaption::GetCaptionRect

See Also	TTinyCaption

Syntax

TRect GetCaptionRect();

Description

Gets the area of the caption for changing or repainting.


See Also

TTinyCaption::PaintCaption


TTinyCaption::GetSysBoxRect

See Also	TTinyCaption

Syntax

TRect GetSysBoxRect();

Description

Returns the size of the system box rectangle.


See Also

TTinyCaption::PaintSysBoxRect


TTinyCaption::GetMinBoxRect

See Also	TTinyCaption

Syntax

TRect GetMinBoxRect();

Description

Returns the size of the minimize box rectangle.


See Also

TTinyCaption::PaintMinBoxRect


TTinyCaption::GetMaxBoxRect

See Also	TTinyCaption

Syntax

TRect GetMaxBoxRect();

Description

Returns the size of the maximize box rectangle.


See Also

TTinyCaption::PaintMaxBoxRect


TTinyCaption::PaintButton

TTinyCaption

Syntax

void PaintButton(TDC& dc, TRect& boxRect, bool pressed);

Description

Paints a blank button.


TTinyCaption::PaintCaption

See Also	TTinyCaption

Syntax

void PaintCaption(bool active);

Description

Calls dc.SelectObject to select the given rectangle and dc.PatBlt to paint the tiny caption bar using the currently selected brush for this device context.


See Also

TDC::SelectObject

TDC::PatBlt


TTinyCaption::PaintCloseBox

See Also	TTinyCaption

Syntax

void PaintCloseBox(TDC& dc, TRect& boxRect, bool pressed);

Description

Paints a close box on the tiny caption bar. You can override the default box if you want to design your own close box.


See Also

TTinyCaption::GetSysBoxRect


TTinyCaption::PaintMaxBox

See Also	TTinyCaption

Syntax

void PaintMaxBox(TDC& dc, TRect& boxRect, bool pressed);

Description

Paints a maximize box on the tiny caption bar.


See Also

TTinyCaption::GetMaxBoxRect


TTinyCaption::PaintMinBox

See Also	TTinyCaption

Syntax

void PaintMinBox(TDC& dc, TRect& boxRect, bool pressed);

Description

Paints a minimize box on the tiny caption bar.


See Also

TTinyCaption::GetMinBoxRect


TTinyCaption::PaintSysBox

See Also	TTinyCaption

Syntax

void PaintSysBox(TDC& dc, TRect& boxRect, bool pressed);

Description

Paints the system box.


See Also

TTinyCaption::GetSysBoxRect


TTinyCaption Response Table Entries

TTinyCaption

Response table entry	Member function

EV_WM_NCACTIVATE	EvNCActivate

EV_WM_NCCALCSIZE	EvNcCalcSize

EV_WM_NCHITTEST	EvNcHitTest

EV_WM_NCPAINT	EvNcPaint

EV_WM_NCLBUTTONDOWN	EvNclButtonDown

EV_WM_LBUTTONUP	EvLButtonUp

EV_WM_MOUSEMOVE	EvMouseMove

EV_WM_SYSCOMMAND	EvSysCommand


TToolBox Class

OWL Hierarchy	Inheritance

Header File

toolbox.h

Description

Derived from TGadgetWindow, TToolBox arranges gadgets in a matrix in which all columns are the same width (as wide as the widest gadget) and all rows are the same height (as high as the highest gadget).

You can specify exactly how many rows and columns you want for your toolbox, or you can let TToolbox calculate the number of columns and rows you need. If you specify AS_MANY_AS_NEEDED, the TToolBox calculates how many rows or columns are needed based on the opposite dimension. For example, if there are twenty gadgets, and you requested four columns, your matrix would have five rows.

Public Constructor

TToolBox(TWindow* parent, int numColumns = 2, int numRows = AS_MANY_AS_NEEDED, TTileDirection direction = Horizontal, TModule* module = 0);

Public Member Functions

void GetDesiredSize(TSize& size);

void Insert(TGadget& gadget, TPlacement = After, TGadget* sibling = 0);

void LayoutSession();

virtual void SetDirection(TTileDirection direction);

Protected Data Members

int NumColumns;

int NumRows;

Protected Member Function

TRect TileGadgets;


TToolBox Public Constructor

TToolBox

Constructor

TToolBox(TWindow* parent, int numColumns = 2, int numRows = AS_MANY_AS_NEEDED, TTileDirection direction = Horizontal, TModule* module = 0);

Description

Constructs a TToolBox object with the specified number of columns and rows and tiling direction. Overlaps the borders of the toolbox with those of the gadget and sets ShrinkWrapWidth to true.


TToolBox::GetDesiredSize

See Also	TToolBox

Syntax

void GetDesiredSize(TSize& size);

Description

Overrides TGadget's GetDesiredSize function and computes the size of the cell by calling GetMargins to get the margins.


See Also

TGadgetWindow::GetDesiredSize


TToolBox::Insert

See Also	TToolBox

Syntax

void Insert(TGadget& gadget, TPlacement = After, TGadget* sibling = 0);

Description

Overrides TGadget's Insert function and tells the button not to notch its corners.


See Also

TGadgetWindow::Insert


TToolBox::LayoutSession

TToolBox

Syntax

void LayoutSession();

Description

Called when a change occurs in the size of the margins of the toolbox or size of the gadgets, LayoutSession gets the desired size and moves the window to adjust to the desired change in size.


TToolBox::SetDirection

TToolBox

Syntax

virtual void SetDirection(TTileDirection direction);

Description

Sets the direction of the tiling--either horizontal or vertical.


TToolBox::NumColumns

TToolBox

Syntax

int NumColumns;

Description

Contains the number of columns for the toolbox.


TToolBox::NumRows

TToolBox

Syntax

int NumRows;

Description

Contains the number of rows for the toolbox.


TToolBox::TileGadgets

See Also	TToolBox

Syntax

TRect TileGadgets;

Description

Tiles the gadgets in the direction requested (horizontal or vertical). Derived classes can adjust the spacing between gadgets.


See Also

TGadgetWindow::TileGadget


TTransferDirection enum

OWL Hierarchy	See Also

Header File

window.h

Syntax

enum TTransferDirection {tdGetData, tdSetData,  tdSizeData};

Description

The TTransferDirection enum describes the following constants that the transfer function uses to determine how to transfer data to and from the transfer buffer:

Constant	Meaning

tdGetData	Retrieve data from the class.

tdSetData	Send data to the class.

tdSizeData	Return the size of data transferred by the class.


See Also

TWindow::Transfer

TWindow::TransferData


TUIHandle Class

See Also	OWL Hierarchy

Header File

uihandle .h

Description

TUIHandle manages and draws various kinds of UI handles, including hatched border handles, and resizing grapples (small squares that appear along the edges) on a rectangle. You can use this class to create a hatched border that encloses various kinds of drawing objects you want to manipulate.

With the help of this class, you can create an application that lets you

Resize the shape of the rectangle by pointing to and grabbing one of the grapples on the border

Move the entire rectangle by clicking in the middle of the rectangle

Although by default a hatched border with eight grapples is created, you can control whether grapples appear. In addition, you can vary the pattern of the border by drawing a dashed frame enclosing a rectangle or a rectangle filled with hatch marks. TuiHandle uses THatch8x8Brush to draw the hatched border.

TUIHandle uses the enum TWhere to return the area where the user points and clicks the mouse (referred to as a hit area).

The following diagram displays a UI handle and identifies several small square grapples where hit testing occurs.

The following code fragment sets up a hatched border and UI grapples for an OLE 2 container application:

// Do the default rectangle painting.

  .

  .

  .

TRect r //...; Insert your rectangle drawing code here.

// Draw 8 grapples with a border on top of the object.

TUIHandle handle(r, TUIHandle::HandlesIn|

                 TUIHandle::Grapples|

                 TUIHandle::HatchBorder, 5);

handle.Paint(dc);

// Insert your code here....

  .

  .

  .

// Draw a hatched border.

TUIHandle handle(r, TUIHandle::HatchBorder, 5);

handle.Paint(dc);

Type Definitions

enum TStyle(HandlesIn, HandlesOut, Framed, DashFramed, Grapples, HatchBorder, HatchRect, InsideSpecial};

enum TWhere{TopLeft, TopCenter, TopRight, MidLeft, MidCenter, MidRight, BottomLeft, BottomCenter, BottomRight, Outside, Inside};

Public Constructors

TUIHandle(const TRect& frame, uint style = HandlesIn|Grapples|HatchBorder, int thickness = 5);

Public Member Functions

TRect GetBoundingRect() const;

static uint16 GetCursorId(TWhere where);

TWhere HitTest(const TPoint& point) const;

void Move(int dx, int dy);

void MoveTo(int x, int y);

void Paint(TDC& dc) const;

void Size(int w, int h);


See Also

THatch8x8Brush


TUIHandle::TStyle enum

TUIHandle

Syntax

enum TStyle{HandlesIn, HandlesOut, Framed, DashFramed, Grapples, HatchBorder, HatchRect, InsideSpecial};

Description

Enumerates the style of the border around the rectangle with combinations of the following styles:

Value	Description

Select one of the following styles:

HandlesIn	Draw handles inside the rectangle

HandlesOut	Draw handles outside the rectangle

Select zero or one of the following styles:

Framed	Draw a solid frame around the rectangle

DashFramed	Draw a dashed frame around the rectangle

Grapples	Draw eight grapples for resizing

Select zero or one of the following styles:

HatchBorder	Draw a hatched handle for moving the border

HatchRect	Draw the entire rectangle filled in with hatch marks

InsideSpecial	Treat the inside hit area in a special way

If a hatched border with grapples is drawn inside a rectangle, it sits within the borders of the outer frame of the rectangle. If a hatched border with grapples is drawn outside the rectangle, it is drawn outside the boundary of the rectangle's frame. In the latter case, the function GetBoundingRect returns a larger rectangle.


TUIHandle::TUIHandle::TWhere enum
TUIHandle::TWhere enum

TUIHandle

Syntax

enum TWhere {TopLeft, TopCenter, TopRight, MidLeft, MidCenter, MidRight, BottomLeft, BottomCenter, BottomRight, Outside, Inside};

Description

TWhere indicates which one of the grapples or handle was hit. TWhere can contain one of the following values:

Value	Description

TopLeft 	The grapple in the top left corner of the border was hit.

TopCenter 	The grapple in the top center of the border was hit.

TopRight	The grapple in the top left right corner of the border was hit.

MidLeft	The grapple in the middle of the left border was hit.

MidCenter	The area in the middle of the rectangle was hit. This indicates that either the hatched frame was hit or inside, non-special area was hit.

MidRight	The grapple in the middle of the right border was hit.

BottomLeft	The grapple in the left corner of the bottom border was hit.

BottomCenter	The grapple in the center of the bottom border was hit.

BottomRight	The grapple in the right corner of the bottom border was hit.

Outside	The hit area is completely outside the object.

Inside	The hit area for the grapple is inside the object and InsideSpecial is set.

The InsideSpecial designation refers to the area inside the rectangle when the hit area needs to be treated specially (for example, because it might contain text or graphics). Normally, if the area inside the rectangle is hit, it means that user wants to move the rectangle. However, if there is text inside the rectangle, the user might click on this area in order to enter text. This latter situation is referred to as an inside special case.

The hit area (Where) can be converted to a row and a column by using the following equations:

Row = Where / 3

Column = Where mod 3

The value of Where ranges from 0 (TopLeft) to 8 (BottomRight) and corresponds to the following areas of a rectangle:

You can then use these values to calculate the movement of the object and to resize the object.


TUIHandle Public Constructors
TUIHandle Public Constructor

TUIHandle

Syntax

TUIHandle(const TRect& frame, uint style = HandlesIn|Grapples|HatchBorder, int thickness = 5);

Description

Constructs a TUIHandle object for the specified frame, with eight grapples drawn in a hatched border and a default thickness of 5 pixels drawn to the inside.


TUIHandle::GetBoundingRect

TUIHandle

Syntax

GetBoundingRect()const;

Description

GetBoundingRect returns a rectangle with the size adjusted according to the thickness. For example, if the handles are outside the rectangle, GetboundingRect returns a larger rectangle. The enum TStyle defines the positions of the handles (whether the handles are defined as HandlesIn or HandlesOut).


TUIHandle::GetCursorId

TUIHandle

Syntax

static uint16 GetCursorId(TWhere where);

Description

Returns the ID of a standard cursor that is appropriate for use over the location specified in the where parameter.


TUIHandle::HitTest

TUIHandle

Syntax

TWhere HitTest(const TPoint& point)const;

Description

Compares a given point (point) to various parts of the rectangle. If the hit was outside the rectangle, HitTest returns Outside. If the hatched border handle of the rectangle was hit, returns MidCenter (inside). For any other hits, HitTest returns the location of the grapple that was hit. The enum TWhere defines the possible hit areas.


TUIHandle::Move

See Also	TUIHandle

Syntax

void Move(int dx, int dy);

Description

Moves the rectangle relative to the values specified in dx and dy.


See Also

TUIHandle::MoveTo


TUIHandle::MoveTo

See Also	TUIHandle

Syntax

void MoveTo(int x, int y);

Description

Moves the rectangle to the given x and y coordinates.


See Also

TUIHandle::Move


TUIHandle::Paint

TUIHandle

Syntax

void Paint(TDC& dc) const;

Description

Paints the TUIHandle object onto the specified device context, dc.


TUIHandle::Size

TUIHandle

Syntax

void Size(int w, int h);

Description

Sets the size of the rectangle according to the measurements specified in w, the width, and h, the height.


TValidator Class

OWL Hierarchy	Inheritance

Header File

validate.h

Description

A streamable class, TValidator defines an abstract data validation object. Although you will never actually create an instance of TValidator, it provides the abstract functions for the other data validation objects.

The VALIDATE.CPP sample program on your distribution disk derives TValidateApp from TApplication in the following manner:

class TValidateApp : public TApplication {

   public:

      TValidateApp() : TApplication("ValidateApp") {}

      void InitMainWindow() {

         MainWindow = new TTestWindow(0, "Validate Dialog Input");

}

The program displays the following message box if the user enters an invalid employee ID:

Sample Validation Message Box

Public Constructor and Destructor

TValidator();

virtual ~TValidator();

Public Member Functions

virtual void Error();

bool HasOption(int option);

virtual bool IsValid(const char far* str);

virtual bool IsValidInput(char far* str, bool suppressFill);

void SetOption(int option);

virtual uint Transfer(char far* str, void* buffer, TTransferDirection direction);

void UnsetOption(int option);

bool Valid(const char far* str);

Protected Data Members

uint16 Options;

Type Definitions

enum TValidatorOptions{voFill, voTransfer, voOnAppend, voReserved };


Sample Validation Message Box


TValidator Public Constructor and Destructor
TValidator Public Constructors and Destructor

TValidator

Constructor

TValidator();

Destructor

virtual ~TValidator();

Description

Constructs an abstract validator object and sets Options fields to 0.

Destructor

Destroys an abstract validator object.


TValidator::Error

TValidator

Syntax

virtual void Error();

Description

Error is an abstract function called by Valid when it detects that the user has entered invalid information. By default, TValidator::Error does nothing, but derived classes can override Error to provide feedback to the user.


TValidator::HasOption

See Also	TValidator

Syntax

bool HasOption(int option);

Description

Gets the Options bits. Returns true if a specified option is set.


See Also

TValidatorOptions enum


TValidator::IsValid

TValidator

Syntax

virtual bool IsValid(const char far* str);

Description

By default, returns true. Derived validator types can override IsValid to validate data for a completed edit control. If an edit control has an associated validator object, its Valid method calls the validator object's Valid method, which in turn calls IsValid to determine whether the contents of the edit control are valid.


TValidator::IsValidInput

TValidator

Syntax

virtual bool IsValidInput(char far* str, bool suppressFill);

Description

If an edit control has an associated validator object, it calls IsValidInput after processing each keyboard event, thus giving validators such as filter validators an opportunity to catch errors before the user fills the entire item or screen.

By default, IsValidInput returns true. Derived data validators can override IsValidInput to validate data as the user types it, returning true if str holds valid data and false otherwise.

str is the current input string. suppressFill determines whether the validator should automatically format the string before validating it. If suppressFill is true, validation takes place on the unmodified string str. If suppressFill is false, the validator should apply any filling or padding before validating data. Of the standard validator objects, only TPXPictureValidator checks suppressFill.

IsValidInput can modify the contents of the input string; for example, it can force characters to uppercase or insert literal characters from a format picture. IsValidInput should not, however, delete invalid characters from the string. By returning false, IsValidInput indicates that the edit control should erase the incorrect characters.


TValidator::SetOption

See Also	TValidator

Syntax

void SetOption(int option);

Description

Sets the bits for the Options data member.


See Also

TValidator::Options

TValidatorOptions enum


TValidator::Transfer

See Also	TValidator

Syntax

virtual uint Transfer(char far* str, void* buffer, TTransferDirection direction);

Description

Allows a validator to set and read the values of its associated edit control. This is primarily useful for validators that check non-string data, such as numeric values. For example, TRangeValidator uses Transfer to read and write values instead of transferring an entire string.

By default, edit controls with validators give the validator the first chance to respond to DataSize, GetData, and SetData by calling the validator's Transfer method. If Transfer returns anything other than 0, it indicates to the edit control that it has handled the appropriate transfer. The default action of TValidator::Transfer is always to return 0. If you want the validator to transfer data, you must override its Transfer method.

Transfer's first two parameters are the associated edit control's text string and the tdGetData or tdSetData data record. Depending on the value of direction, Transfer can set str from buffer or read the data from str into buffer. The return value is always the number of bytes transferred.

If direction is tdSizeData, Transfer doesn't change either str or buffer; it just returns the data size. If direction is tdSetData, Transfer reads the appropriate number of bytes from buffer, converts them into the proper string form, and sets them into str, returning the number of bytes read. If direction is tdGetData, Transfer converts str into the appropriate data type and writes the value into buffer, returning the number of bytes written.


See Also

TTransferDirection enum


TValidator::UnsetOption

See Also	TValidator

Syntax

void UnsetOption(int option);

Description

Unsets the bits specified in the Options data member.


See Also

TValidator::Options

TValidatorOptions enum


TValidator::Valid

TValidator

Syntax

bool Valid(const char far* str);

Description

Returns true if IsValid returns true. Otherwise, calls Error and returns false. A validator's Valid method is called by the Valid method of its associated edit control.

Edit controls with associated validator objects call the validator's Valid method under two conditions. The first condition is when the edit control's ofValidate option is set and the edit control calls Valid when it loses focus. The second condition is when the dialog box that contains the edit control calls Valid for all its controls, usually because the user requested to close the dialog box or to accept an entry screen.


TValidator::Options

See Also	TValidator

Syntax

uint16 Options;

Description

Abitmap member used to control options for various descendants of TValidator. By default, the TValidator constructor clears all the bits in Options.


See Also

TVAlidatorOptions enum

TValidator::SetOption

TValidator::UnsetOption


TValidatorOptions enum

Header File

validate.h

Syntax

enum TValidatorOptions {voFill, voTransfer, voOnAppend, voReserved };

Description

Constants that represent bits in the bitmapped Options word in validator objects.

Constant	Meaning

voFill	Used by picture validators to indicate whether to fill in literal characters as the user types.

voTransfer	The validator handles data transfer for the input line.  Currently only used by range validators.

voOnAppend	Used by picture validators to determine how to interact with edit controls.

voReserved	The bits in this mask are reserved.


TValidator::TXValidator class

OWL Hierarchy	Inheritance

Header File

validate.h

Description

A nested class, TXValidator describes an exception that results from an invalid validator object. That is, if a validator expression is not valid, this exception is thrown.

Public Constructor

TXValidator(uint resId = IDS_VALIDATORSYNTAX);


TValidator::TXValidator Public Constructor

TValidator::TXValidator

Syntax

TXValidator(uint resId = IDS_VALIDATORSYNTAX);

Description

Constructs a TXValidator object, setting the resource ID to IDS_VALIDATORSYNTAX string resource.


TVbxControl Class

See Also

OWL Hierarchy	Inheritance

Header File

vbxctl.h

Description

Derived from TControl, TVbxControl provides the interface for Visual Basic (VBX) controls. You can use this class to get or set the properties of VBX controls. Under certain conditions, you can also use additional methods for processing controls. Both 16- and 32-bit programs can use these VBX controls.

You can manipulate the control's properties using either an index value or a name. Several overloaded GetProp functions are provided so that you can access different types of properties. Similarly, several overloaded SetProp functions let you set the properties of controls using either the name of the VBX control or the index value. Consult the documentation for your VBX controls to find the name that corresponds to the property you want to manipulate.

The VBXCTLX.CPP sample program on your distribution disks displays the following VBX controls:

Sample VBX Controls

TVbxControl provides event-handling functions that process requests to compare, delete, draw, or measure VBX controls. If you want the TVbxControl object to process additional VBX events, you can derive a class from TVbxControl and add a response table that has entries for the events you want processed. For information about creating response tables and handling VBX messages, see TVbxEventHandler.

Public Constructors and Destructor

TVbxControl(TWindow* parent, int id, const char far* vbxName, const char far* vbxClass, const char far* title, int x, int y, int w, int h, long initLen = 0, void far* initData = 0, TModule* module = 0);

TVbxControl(TWindow* parent, int resourceId, TModule* module = 0);

~TVbxControl();

Public Member Functions

bool AddItem(int index, const char far* item);

bool Drag(int action);

int GetEventIndex(const char far* name);

const char far* GetEventName(int eventindex);

HCTL GetHCTL();

int GetNumEvents();

int GetNumProps();

bool GetProp(int propIndex, int& value, int arrayIndex = -1);

bool GetProp(int propIndex long& value, int arrayIndex = -1);

bool GetProp(int propIndex, ENUM& value, int arrayIndex=-1);

bool GetProp(int propIndex, HPIC& value, int arrayIndex=-1);

bool GetProp(int propIndex float& value, int arrayIndex = -1);

bool GetProp(int propIndex string& value, int arrayIndex = -1);

bool GetProp(int propIndex, COLORREF value, int arrayIndex = -1);

bool GetProp(const char far* name, int& value, int arrayIndex = -1);

bool GetProp(const char far* name, long& value, int arrayIndex = -1);

bool GetProp(const char far* name, float& value, int arrayIndex = -1);

bool Getprop(const char far* name, ENUM& value, int arrayIndex=-1);

bool Getprop(const char far* name, HPIC& value, int arrayIndex=-1);

bool GetProp(const char far* name, string& value, int arrayIndex = -1);

bool GetProp(const char far* name, COLORREF value, int arrayIndex = -1);

int GetPropIndex(const char far* name);

const char far* GetPropName(int propIndex);

int GetPropType(int propIndex);

int GetPropType(char far* name);

bool IsArrayProp(int propIndex);

bool IsArrayProp(char far* name);

bool Method(int method, long far* args);

bool Move(long x, long y, long w, long h);

bool Refresh();

bool RemoveItem(int index);

bool SetProp(int propIndex, int value, int arrayIndex = -1);

bool SetProp(int propIndex, long value, int arrayIndex = -1);

bool SetProp(int propIndex, ENUM value, int arrayIndex=-1);

bool SetProp(int propIndex, HPIC value, int arrayIndex=-1);

bool SetProp(int propIndex, float value, int arrayIndex = -1);

bool SetProp(int propIndex, const string& value, int arrayIndex = -1);

bool SetProp(int propIndex, const char far* value, int arrayIndex = -1);

bool SetProp(int propIndex, COLORREF value, int arrayIndex = -1);

bool SetProp(const char far* name, int value, int arrayIndex = -1);

bool SetProp(const char far* name, long value, int arrayIndex = -1);

bool SetProp(const char far* name, ENUM value, int arrayIndex=-1);

bool SetProp(const char far* name, HPIC value, int arrayIndex = -1);

bool SetProp(const char far* name, float value, int arrayIndex = -1);

bool SetProp(const char far* name, const string& value, int arrayIndex = -1);

bool SetProp(const char far* name, const char far* value, int arrayIndex = -1);

bool SetProp(const char far* name, COLORREF value, int arrayIndex = -1);

void SetUpWindow();

Protected Member Functions

char far* GetClassName();

bool GetVBXProperty(int propIndex, void far* value, int arrayIndex = -1);

void PerformCreate(int menuOrId);

bool SetVBXProperty(int propIndex, int32 value, int arrayIndex=-1);

Response Table Entries

EV_ macros and member functions


See Also

VisualBasic Control Objects Overview


Sample VBX Controls


TVbxControl Public Constructors and Destructor

TVbxControl

Constructors

Syntax 1

TVbxControl(TWindow* parent, int id, const char far* vbxName, const char far* vbxClass, const char far* title, int x, int y, int w, int h, long initLen = 0, void far* initData = 0, TModule* module = 0);

Description

Constructs a VBX control where parent points to the parent window, id is the control's ID, vbxName is the name of the file containing the VBX control, vbxClass is the VBX class name, title is the control's caption, x and y are the coordinates in the parent window where the controls are to be placed, w and h are the width and height of the control, and module is the library resource ID for the control.

Syntax 2

TVbxControl(TWindow* parent, int resourceId, TModule* module = 0);

Description

If a VBX control is part of a dialog resource, its ID can be used to construct a corresponding (or alias) ObjectWindows object. You can use this constructor if a VBX control has already been defined in the application's resource file. resourceId is the resource ID of the VBX control in the resource file.

Destructor Syntax

~TVbxControl();

Description

Destroys the TVbxControl object.


TVbxControl::AddItem

TVbxControl

Syntax

bool AddItem(int index, const char far* item);

Description

Adds an item (item) to the list of VBX control items at the specified index (index). Returns nonzero if successful.


TVbxControl::Drag

TVbxControl

Syntax

bool Drag(int action);

Description

Controls the drag and drop state of the VBX control according to the value of action, which can be 0 (cancel a drag operation), 1 (begin dragging a control), or 2 (end dragging a control).


TVbxControl::GetEventIndex

TVbxControl

Syntax

int GetEventIndex(const char far* name);

Description

Returns the index of the event associated with the name of the event passed in name. Returns -1 if an error occurs.


TVbxControl::GetEventName

TVbxControl

Syntax

const char far* GetEventName(int eventindex);

Description

Returns a string containing the name of an event associated with the integer event index number (eventindex). Returns 0 if an error occurs.


TVbxControl::GetHCTL

TVbxControl

Syntax

HCTL GetHCTL();

Description

Returns a handle to a VBX control associated with this TVbxControl object.


TVbxControl::GetNumEvents

TVbxControl

Syntax

int GetNumEvents();

Description

Returns the total number of events associated with the VBX control.


TVbxControl::GetNumProps

TVbxControl

Syntax

int GetNumProps();

Description

Returns the total number of properties associated with the VBX control.


TVbxControl::GetProp

See Also	TVbxControl

Form 1

bool GetProp(int propIndex, int& value, int arrayIndex = -1);

Form 2

bool GetProp(int propIndex, long& value, int arrayIndex = -1);

Form 3

bool GetProp(int propIndex, ENUM& value, int arrayIndex=-1);

Form 4

bool GetProp(int propIndex, HPIC& value, int arrayIndex=-1);

Form 5

bool GetProp(int propIndex, float& value, int arrayIndex = -1);

Form 6

bool GetProp(int propIndex, string& value, int arrayIndex =
-1);

Form 7

bool GetProp(int propIndex, COLORREF value, int arrayIndex = -1);

Form 8

bool GetProp(const char far* name, int& value, int arrayIndex = -1);

Form 9

bool GetProp(const char far* name, long& value, int arrayIndex = -1);

Form 10

bool GetProp(const char far* name, float& value, int arrayIndex = -1);

Form 11

bool GetProp(const char far* name, ENUM& value, int arrayIndex=-1);

Form 12

bool Getprop(const char far* name, HPIC& value, int arrayIndex=-1);

Form 13

bool GetProp(const char far* name, string& value, int arrayIndex = -1);

Form 14

bool GetProp(const char far* name, COLORREF value, int arrayIndex = -1);

Description

Form 1: Gets an integer property value. An overloaded function, GetProp gets a VBX control property using an index value. propIndex is the index value of the property whose value you want to get. value is a reference to the variable that will receive the property values. arrayIndex, an optional argument, specifies the position of the value in an array property if the property is an array type. If the property isn't an array type, arrayIndex defaults to -1. See the third-party reference guide for your VBX controls to determine a property's data type. GetProp returns nonzero if successful. To get the property by specifying the property index, use one of the following six GetProp functions.

Form 2: Gets a long property value.

Form 3: Gets an enumerated property value. For example, a list of options associated with a font style might be defined as an enumerated type.

Form 4: Gets a picture (value). HPIC is a handle to the picture.

Form 5: Gets a floating-point property value.

Form 6: Gets a string property value.

Form 7: Gets a color property value.

Form 8: Returns an integer data value. An overloaded function, GetProp gets a VBX control property. propIndex is the index value of the property whose value you want to get. value is a reference to the variable that will receive the property value. arrayIndex, an optional argument, specifies the position of the value in an array property if the property is an array type. If the property isn't an array type, arrayIndex defaults to -1. GetProp returns nonzero if successful. To get the property by specifying the name of the property, use one of the following five GetProp functions.

Form 9: Gets a long property value.

Form 10: Gets a floating-point property value.

Form 11: Gets an enumerated property value.

Form 12: Gets a picture (value) property value. HPIC is a handle to the picture.

Form 13: Gets a string property value.

Form 14: Gets a string color property value.


See Also

TVbxControl::SetProp


TVbxControl::GetPropIndex

TVbxControl

Syntax

int GetPropIndex(const char far* name);

Description

Gets the integer index value for the property name passed in name. Returns -1 if an error occurs. This usually indicates that the property name passed in name couldn't be located.


TVbxControl::GetPropName

TVbxControl

Syntax

const char far* GetPropName(int propIndex);

Description

Gets the name for the property index passed in index. Returns 0 if an error occurs.


TVbxControl::GetPropType

TVbxControl

Form 1

int GetPropType(int propIndex);

Form 2

int GetPropType(char far* name);

Description

Form 1 gets the type for the property specified by index. Form 2 gets the property string type specified by name. Returns 0 if an error occurs. The following table lists the names of the property types and their corresponding C++ data types.

Property type	C++ type

PTYPE_CSTRING	HSZ

PTYPE_SHORT	short

PTYPE_LONG	int32

PTYPE_BOOL	bool

PTYPE_COLOR	uint32 or COLORREF

PTYPE_ENUM	uint8 or ENUM

PTYPE_REAL	float

PTYPE_XPOS	int32 (Twips)

PTYPE_XSIZE	int32(Twips)

PTYPE_YPOS	int32 (Twips)

PTYPE_YSIZE	int32 (Twips)

PTYPE_PICTURE	HPIC

PTYPE_BSTRING	HLSTR


TVbxControl::IsArrayProp

TVbxControl

Form 1

bool IsArrayProp(int propIndex);

Form 2

bool IsArrayProp(char far* name);

Description

Returns true if the property specified by index  (Form 1) or name  (Form 2) is an array property.


TVbxControl::Method

TVbxControl

Syntax

bool Method(int method, long far* args);

Description

Used for invoking customized methods, Method returns true if a VBX control can respond to the specified method (method).


TVbxControl::Move

TVbxControl

Syntax

bool Move(long x, long y, long w, long h);

Description

Moves a VBX control to the coordinates specified in x and y, which designate the upper left corner screen coordinates. Resizes the VBX control to w twips wide by h twips high. Returns nonzero if successful.


TVbxControl::Refresh

TVbxControl

Syntax

bool Refresh();

Description

Repaints the control's display area.


TVbxControl::RemoveItem

TVbxControl

Syntax

bool RemoveItem(int index);

Description

Removes an item (specified by index). The item could be removed from a list box, a combo box, or a database, for example.


TVbxControl::SetProp

See Also	TVbxControl

Form 1

bool SetProp(int propIndex, int value, int arrayIndex = -1);

Form 2

bool SetProp(int propIndex, long value, int arrayIndex = -1);

Form 3

bool SetProp(int propIndex, ENUM value, int arrayIndex=-1);

Form 4

bool SetProp(int propIndex, HPIC value, int arrayIndex=-1);

Form 5

bool SetProp(int propIndex, float value, int arrayIndex = -1);

Form 6

bool SetProp(int propIndex, const string& value, int arrayIndex = -1);

Form 7

bool SetProp(int propIndex, const char far* value, int arrayIndex = -1);

Form 8

bool SetProp(int propIndex, COLORREF value, int arrayIndex = -1);

Form 9

bool SetProp(const char far* name, int value, int arrayIndex = -1);

Form 10

bool SetProp(const char far* name, long value, int arrayIndex = -1);

Form 11

bool SetProp(const char far* name, ENUM value, int arrayIndex=-1);

Form 12

bool SetProp(const char far* name, HPIC value, int arrayIndex = -1);

Form 13

bool SetProp(const char far* name, float value, int arrayIndex = -1);

Form 14

bool SetProp(const char far* name, const string& value, int arrayIndex = -1);

Form 15

bool SetProp(const char far* name, const char far* value, int arrayIndex = -1);

Form 16

bool SetProp(const char far* name, COLORREF value, int arrayIndex = -1);

Description

Form 1: Sets the property to an integer value. An overloaded function, SetProp sets a VBX control property. propIndex is the index number of the property whose value you want to set. value specifies the new value for the property. arrayIndex specifies the position of the value in an array property if the property is an array type. If the property isn't an array type, arrayIndex defaults to -1. To set the property by passing the property's index value, use one of the following six SetProp functions.

Form 2: Sets the property to a long value.

Form 3: Sets the property to an enumerated value.

Form 4: Sets a picture to an HPIC, or picture, value.

Form 5: Sets the property to a floating-point value.

Form 6: Sets the property to a string value.

Form 7: Sets the property to a character string value.

Form 8: Sets the property to a color value.

Form 9: Sets the property to an integer value. An overloaded function, SetProp sets a VBX control property. arrayIndex specifies the position of the value in an array property if the property is an array type. If the property isn't an array type, arrayIndex defaults to -1. To set the property by using the property's name, use one of the following six SetProp functions.

Form 10: Sets the property to a long value.

Form 11: Sets the property to an enumerated value.

Form 12: Sets the picture property to an HPIC, or picture, value.

Form 13: Sets the property to a floating-point value.

Form 14: Sets the property to a string value.

Form 15: Sets the property to a character string value.

Form 16: Sets the property to a color string value.


See Also

TVbxControl::GetProp


TVbxControl::SetupWindow
TVbxControl::SetpWindow

TVbxControl

Syntax

void SetupWindow();

Description

A VBX control has an HWND plus a VBX handle. Usually, the VBX control handle is created first. However, if the window has already been created, you can use this function to extract the VBX control handle.


TVbxControl::GetClassName

TVbxControl

Syntax

char far* GetClassName();

Description

Gets the name of the VBX window class.


TVbxControl::GetVBXProperty

TVbxControl

Syntax

bool GetVBXProperty(int propIndex, void far* value, int arrayIndex = -1);

Description

Returns nonzero if the specified property exists. propIndex specifies the index value of the integer property whose value you want to get. value points to the variable where the value will be stored.


TVbxControl::PerformCreate

TVbxControl

Syntax

void PerformCreate(int menuOrId);

Description

Creates a new control window and associates the VBX control with the window. Establishes the control ID, the VBX control name and class, and the window caption. Sets Attr.style to the window style of the control, Attr.X and Attr.Y to the upper-left screen coordinates of the control, and Attr.W and Attr.H to the width and height of the control.


TVbxControl::SetVBXProperty

TVbxControl

Syntax

bool SetVBXProperty(int propIndex, int32 value, int arrayIndex=-1);

Description

Returns nonzero if the specified property value is set, or 0 if unsuccessful. propindex is the index number of the property whose value you want to set. value is the value to be stored. An optional argument, arrayIndex, which is -1 by default, specifies the index value in an array of values of the property to be set.


TVbxControl::Response Table Entries

TVbxControl

Response table entry	Member function

The TVbxControl class has no response table entries.


TVbxEventHandler Class

See Also

OWL Hierarchy	Inheritance

Header File

vbxctl.h

Description

Derived from TEventHandler, TVbxEventHandler handles events from VBX controls. Although you never need to modify this class, TVbxEventHandler needs to be mixed in with your window class so that your window class can receive events from VBX controls. For example,

class TMyWindow:public TWindow, public TVbxEventHandler

{

// Include class definition here.

}

The following diagram illustrates the flow of information between VBX controls, parent windows, and response tables:

When a VBX control fires an event (sends an event message), the following sequence of events occurs:

1.	The VBX Control sends a WM_VBXFIREEVENT message to TMyWindow.

2.	TMyWindow's TVbxEventHandler finds a WM_VBXFIREEVENT message in its response table and calls EvVbxDispatch.

3.	If a child window is present, EvVbxDispatch dispatches the event to the child.

4.	If there is an event-handling function in the child window's response table, the child window handles the event.

5.	If there is no child window, or the child window doesn't handle the event, EvVbxDispatch dispatches the event to TMyWindow's response table.

In other words, when a VBX control sends a WM_VBXFIREEVENT message, the parent window's TVbxEventHandler catches this message first, converts it into a form understood by a window's response table, and attempts to send the converted message to the child window. If there is no child window or if the child window doesn't handle the message, TVbxEventHandler sends the converted message to the parent window. When the parent window receives the message, it calls the handler function that corresponds to the message.

Two response table macros, EV_VBXEVENTNAME and EV_VBXEVENTINDEX, map VBX events to handler functions. Of the two macros, EV_VBXEVENTNAME is more commonly used. EV_VBXEVENTINDEX is intended for use with code generators, which can determine the event index values for a VBX control. Both macros call an event handler function and point to the VBXEVENT structure. A typical EV_VBXEVENTNAME response table entry might be

EV_VBXEVENTNAME(IDC_BUTTON1, "MouseMove", EvMouseMove);

In this response table, IDC_BUTTON1 is the event ID, "MouseMove" is the event name, and EvMouseMove is the handler function.

The lparam of a WM_VBXFIREEVENT message points to a VBXEVENT structure, which holds information about the event and the control that generated the event. The VBXEVENT structure contains the following members:

typedef struct VBXEVENT {

  HCTL    Control;

  HWND    Window;

  int     ID;

  int     EventIndex;

  LPCSTR  EventName;

  int     NumParams;

  LPVOID  ParamList;

} VBXEVENT;

The structure members are described in the following table:

Member	Description

Control	A handle to the VBX control sending the message.

Window	The handle of the VBX control window.

ID	The ID of the VBX control.

EventIndex	The event index.

EventName	The name of the event.

NumParams 	The number of event arguments.

ParamList	A pointer to a list of pointers to the event's arguments. The ParamList data member provides access to the actual arguments of the event.

To handle VBX events, your program uses an event-handling function. In the following example, EvMouseMove is the name of the handler function, which passes a pointer to the VBXEVENT event structure. VBX_EVENTARGNUM is the macro that takes event, type, and an index number as its parameters. event references the VBXEVENT structure, short is the event argument type, and 0 and 1 are the index numbers of the argument. The argument types and indexes can be found in the documentation for the VBX control.

void EvMouseMove(VBXEVENT FAR* event)

{

   short X = VBX_EVENTARGNUM(event, short, 0);

   short Y = VBX_EVENTARGNUM(event, short, 1);

}

Because VBX controls were originally designed to be used with Visual Basic, their event arguments are documented in terms of Basic data types. The following table lists the Basic types, their C++ equivalents, and macros:

Basic	C++	Macro

Boolean	short	VBX_EVENTARGNUM(event, short, index)

Control	HCTL	VBX_EVENTARGNUM(event, HCTL, index)

Double	double	VBX_EVENTARGNUM(event, double, index)

Enum	short	VBX_EVENTARGNUM(event, short, index)

Integer	short	VBX_EVENTARGNUM(event, short, index)

Long	long	VBX_EVENTARGNUM(event, long, index)

Single	float	VBX_EVENTARGNUM(event, float, index)

String	HLSTR	VBX_EVENTARGSTR(event, index)

The following table lists the standard VBX events and corresponding arguments that the Borland C++ VBX emulation library supports:

Event	Arguments

Click	None

DblClick	None

DragDrop	Source as Control, X as Integer, Y as Integer

DragOver	Source as Control, X as Integer, Y as Integer, State as Integer

GotFocus 	None

KeyDown	Key as Integer, Shift as Integer

KeyPress	Key as Integer, Shift as Integer

KeyUp	Key as Integer, Shift as Integer

LostFocus	None

MouseDown	X as Integer, Y as Integer

MouseMove	X as Integer, Y as Integer, Shift as Integer, Button as Integer

MouseUp	X as Integer, Y as Integer, Shift as Integer, Button as Integer

For the DragOver event, the state argument can be one of the following values:

0	The source control is being dragged within a target's range.

1	The source control is being dragged out of a target's range.

2	The source control is being moved from one position in the target to another.

For both the DragOver and DragDrop events, the Control argument type should be translated to HCTL (a handle to the VBX control) for C++. The X and Y values are in pixels, not twips.

If a standard VBX event has a Shift key argument, the argument has these bit values:

Key	Bit value

Shift	0x1

Ctrl	0x2

Alt	0x4 (Used in connection with a Menu selection)

If a standard VBX event has a Button key argument, the argument has these bit values:

Button	Bit value

Left	0x1

Right 	0x2

Middle	0x4

The following example shows how you might use the Shift key arguments. For example, if you want the VBX control to perform some action when the mouse is moved and the Shift key is pressed, you could write a function such as

void EvMouseMove(VBXEVENT FAR* event)

{

   short X = VBX_EVENTARGNUM(event, short, 0);

   short Y = VBX_EVENTARGNUM(event, short, 1);

   short Shift = VBX_EVENTARGNUM(event, short, 2);

   short Button = VBX_EVENTARGNUM(event, short, 3);

   if (shift & 0x2)

      MessageBox ("The control key is pressed.");

}

Borland C++ uses pixels to express the X and Y coordinate arguments of standard VBX events. This differs from Visual Basic, which expresses coordinates in twips (1/20th of a point or 1/1440 of an inch). Custom events are usually expressed in terms of twips. You can use these functions to convert between pixels and twips:

Function	Meaning

VBXPix2TwpX	Converts an X argument from pixels to twips

VBXPix2TwpY	Converts a Y argument from pixels to twips

VBXTwp2PixX	Converts an X argument from twips to pixels

VBXTwp2PixY	Converts a Y argument from twips to pixels

Protected Member Function

LRESULT EvVbxDispatch(WPARAM wp, LPARAM lp);

LRESULT EvVbxInitForm(WPARAM wp, LPARAM lp);

Response Table Entries

EV_ macros and member functions


See Also

Visual Basic Control Objects Overview


TVbxEventHandler::EvVbxDispatch

TVbxEventHandler

Syntax

LRESULT EvVbxDispatch(WPARAM wp, LPARAM lp);

Description

After TVbxEventHandler receives a WM_VBXFIREEVENT message from the parent window, it calls EvVbxDispatch, which sends the message to the correct event-handling function and passes a pointer to the VBXEVENT structure.


TVbxEventHandler::EvVbxInitForm

TVbxEventHandler

Syntax

LRESULT EvVbxInitForm(WPARAM wp, LPARAM lp);

Description

Initializes a dialog box that contains VBX controls.


TVbxEventHandler::Response Table Entries

TVbxEventHandler

Response table entry	Member function

EV_MESSAGE(WM_VBXFIREEVENT, EvVbxDispatch)	EvVbxDispatch

EV_MESSAGE(WM_VBXINITFORM, EvVbxinitForm)	EvVbxInitForm


TView Class

OWL Hierarchy	Inheritance

Header File

docview.h

Description

Derived virtually from both TEventHandler and TStreamableBase, TView is the interface presented to a document so it can access its client views. Views then call the document functions to request input and output streams. Views own the streams and are responsible for attaching and deleting them.

Instead of creating an instance of TView, you create a derived class that can implement TView's virtual functions. The derived class must have a way of knowing the associated window (provided by GetWindow) and of describing the view (provided by GetViewName). The view must also be able to display the document title in its window (SetDocTitle).

Classes derived from TView may need to handle several notification messages. For example, if a view is associated with a window that can gain focus, then the view should handle the vnIsWindow  notification message.

View classes can take various forms. For example, a view class can be a window (through inheritance), can contain a window (an embedded object), can reference a window, or can be contained within a window object. A view class might not even have a window, as in the case of a voice mail or a format converter. Some remote views (for example, those displayed by DDE servers) might not have local windows.

Other viewer classes derived from TView include TEditView, TListView, and TWindowView. These classes display different types of data: TEditView displays unformatted text files, TListView displays text information in a list box, and TWindowView is a basic viewer from which you can derive other types of viewers such as hexadecimal file viewers.

For OLE-enabled applications, use TOleView, which supports views for embedded objects and compound documents.

Public Data Members

enum {PrevProperty = 0, ViewClass, ViewName, NextProperty,};

void far* Tag;

Public Constructor and destructor

TView(TDocument& doc);

virtual ~TView();

Public Member Functions

virtual int FindProperty(const char far* name);

TDocument& GetDocument();

static unsigned GetNextViewId();

virtual int GetProperty(int index, void far* dest, int textlen=0);

unsigned GetViewId();

TMenuDescr* GetViewMenu();

virtual const char far* GetViewName()=0;

virtual TWindow* GetWindow();

bool IsOK();

virtual int PropertyCount();

virtual int PropertyFlags(int index);

virtual const char* PropertyName(int index);

virtual bool SetDocTitle(const char far* docname, int index)

virtual bool SetProperty(int index, const void far* src);

void SetViewMenu(TMenuDescr* menu);

Protected Data Member

TDocument* Doc;

Protected Member Functions

void NotOK();


TView Property enum

TView

Syntax

enum {PrevProperty = 0, ViewClass, ViewName, NextProperty,};

Description

These property values, defined for TView, are available in classes derived from TView. PrevProperty and NextProperty are delimiters for every document's property list.


TView::Tag

TView

Syntax

void far* Tag;

Description

Holds a pointer to the application-defined data. Typically, you can use Tag to install a pointer to your own application's associated data structure. TView zeros Tag during construction and does not access it again.


TView Public Constructor and Destructor

TView

Constructor

TView(TDocument& doc);

Description

Constructs a TView object of the document associated with the view. Sets the private data member ViewId to NextViewId. Calls TDocument's private member function AttachView to attach the view to the associated document.

Destructor

virtual ~TView();

Description

Frees a TView object and calls TDocument's private member function DetachView to detach the view from the associated document.


TView::FindProperty

See Also	TView

Syntax

virtual int FindProperty(const char far* name);

Description

Gets the property index, given the property name (name). Returns 0 if the name is not found.


See Also

pfxxxx property access constants


TView::GetDocument

TView

Syntax

TDocument& GetDocument();

Description

Returns a reference to the view's document.


TView::GetNextViewId

TView

Syntax

static unsigned GetNextViewId{};

Description

Returns the next view ID to be assigned.


TView::GetProperty

See Also	TView

Syntax

virtual int GetProperty(int index, void far* dest, int textlen=0);

Description

Returns the total number of properties, where index is the property index, dest contains the property data, and textlen is the size of the property array. If textlen is 0, property data is returned as binary data; otherwise, property data is returned as text data.


See Also

pfxxxx property access constants

TView::SetProperty


TView::GetViewId

TView

Syntax

unsigned GetViewId();

Description

Returns the unique ID for this view.


TView::GetViewMenu

TView

Syntax

TMenuDescr* GetViewMenu();

Description

Returns the menu descriptor for this view. This can be any existing TMenuDescr object. If no descriptor exists, ViewMenu is 0.


TView::GetViewName

See Also	TView

Syntax

virtual const char far* GetViewName()=0;

Description

Pure virtual function that returns 0. Override this function in your derived class to return the name of the class.


See Also

TEditView::StaticName

TEditView::GetViewName


TView::GetWindow

See Also	TView

Syntax

virtual TWindow* GetWindow()

Description

Returns the TWindow instance associated with the view, or 0 if no view exists.


See Also

TeditView::GetWindow


TView::IsOK

See Also	TView

Syntax

bool IsOK();

Description

Returns a nonzero value if the view is successfully constructed.


See Also

TView::NotOK


TView::PropertyCount

See Also	TView

Syntax

virtual int PropertyCount();

Description

Gets the total number of properties for the TDocument object. Returns NextProperty -1.


See Also

pfxxxx property access constants


TView::PropertyFlags

See Also	TView

Syntax

virtual int PropertyFlags(int index);

Description

Returns the attributes of a specified property given the index of the property whose attributes you want to retrieve.


See Also

pfxxxx property access constants

TView::FindProperty

TView::PropertyName


TView::PropertyName

See Also	TView

Syntax

virtual const char* PropertyName(int index);

Description

Returns the text name of the property given the index value.


See Also

pfxxxx property access constants

TView::FindProperty


TView::SetDocTitle

See Also	TView

Syntax

virtual bool SetDocTitle(const char far* docname, int index)

Description

Stores the document title.


See Also

TWindow::SetDocTitle


TView::SetProperty

See Also	TView

Syntax

virtual bool SetProperty(int index, const void far* src);

Description

Sets the value of the property, given the index of the property, and src, the data type (either binary or text) to which the property must be set.


See Also

pfxxxx property access constants

TView::GetProperty


TView::SetViewMenu

See Also	TView

Syntax

void SetViewMenu(TMenuDescr* menu);

Description

Sets the menu descriptor for this view. This can be any existing TMenuDescr object. If no descriptor exists, ViewMenu is 0.


See Also

TView::GetViewMenu


TView::Doc

TView

Syntax

TDocument* Doc;

Description

Holds the current document.


TView::NotOK

TView

Syntax

void NotOK();

Description

Sets the view to an invalid state, causing IsOK to return 0.


ViewId

A TView private data member declared as follows in docview.h:

unsigned ViewId; // unique ID for this view, used for controls


NextViewId

A TView private data member declared as follows in docview.h:

static unsigned NextViewId; // next view ID to be assigned


TWidthHeight enum

OWL Hierarchy	See Also

Header File

layoutco.h

Syntax

enum TWidthHeight{lmWidth = lmCenter = 1, lmHeight};

Description

Used by the TLayoutConstraint  struct,  TWidthHeight enumerates the values that control the width (lmWidth) and height (lmHeight) of the window.


See Also

TLayoutConstraint struct


TWindowAttr struct

OWL Hierarchy

Header File

window.h

Description

Holds TWindow attributes set during construction of a window. Your program controls a window's creation by passing these values to one of TWindow's creation routines. If the window is streamed, these attributes are also used for re-creation.

Public Data Members

TResId AccelTable;

uint32 ExStyle;

int Id;

TResId Menu;

char far* Param;

uint32 Style;

int X, Y, W, H;

Type Definitions

enum TWindowFlag


TWindowAttr::AccelTable

See Also	TWindowAttr struct

Syntax

TResID AccelTable;

Description

Holds the resource ID for the window's accelerator table.


See Also

TApplication::HAccTable

TWindow::LoadAcceleratorTable


TWindowAttr::ExStyle

See Also	TWindowAttr struct

Syntax

uint32 ExStyle;

Description

Contains the extended style values of your window. These can be any one of the extended style constants (WS_EX_DLGMODALFRAME, WS_EX_NOPARENTNOTIFY, WS_EX_TOPMOST, WS_EX_SHADOW). See  Twindow::AdjustWindowRectEx  for a description of these constants.


See Also

TWindow::AdjustWindowRectEx


TWindowAttr::Id

TWindowAttr struct

Syntax

int Id;

Description

Contains the identifier of the child window. For a dialog box control, Id is its resource identifier. If Win32 is defined, Id is set to GetWindowLong ; otherwise Id is set to GetWindowWord.


TWindowAttr::Menu

TWindowAttr struct

Syntax

TResId Menu;

Description

Contains the resource ID for the menu associated with this window. If no menu exists, Menu is 0.


TWindowAttr::Param

TWindowAttr struct

Syntax

char far* Param;

Description

Contains a value that is passed to Windows when the window is created. This value identifies a data block that is then available in the message response functions associated with WM_CREATE. Param is used by TMDIClient and can be useful when converting non-ObjectWindows code.


TWindowAttr::Style

See Also	TWindowAttr struct

Syntax

uint32 Style;

Description

Contains the values that define the style, shape, and size of your window. Although TWindow sets Attr.Style to WS_CHILD and WS_VISIBLE, you can also use other combinations of the following style constants:

Value	Meaning

WS_BORDER	Creates a window with a thin lined border

WS_CAPTION	Creates a window with a title bar.

WS_CHILD	Creates a child windows. Cannot be used with popup styles.

WS_CHILDWINDOW	Creates a child window.

WS_CLIPCHILDREN	Used when creating a parent window. Excludes the area occupied by child windows when drawing takes place within the parent window.

WS_CLIPSIBLINGS	Clips child windows relative to the child window that receives a paint message.

WS_DISABLED	Creates a window that cannot receive user input.

WS_DLGFRAME	Creates a window having a typical dialog box style (without a title bar).

WS_GROUP	Indicates the first control in a group of controls, which the user can change by pressing the direction keys.

WS_HSCROLL	Window has a horizontal scroll bar.

WS_MAXIMIZE	Window is initially maximized.

WS_MAXIMIZEBOX	Window has a maximize button.

WS_MINIMIZE	Window is initially minimized.

WS_MINIMIZEBOX	Window has a minimize button.

WS_OVERLAPPED	Creates an overlapped window with a title bar and a border.

WS_OVERLAPPEDWINDOW	Overlapped window has the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, WS_THICKFRAME, WS_MINIMIZEBOX, and WS_MAXIMIZEBOX styles.

WS_POPUP	Creates a popup window. Cannot be used with child window styles.

WS_POPUPWINDOW	Creates a popup window with WS_BORDER, WS_POPUP, and WS_SYSMENU styles. The WS_CAPTION and WS_POPUPWINDOW styles combine to create a system menu.

WS_SYSMENU	Window has a system menu box in its title bar. Must also indicate the WS_CAPTION style.

WS_TABSTOP	Control can receive the keyboard focus when TAB key is pressed.

WS_THICKFRAME	Window has a border that lets you change the window size.

WS_VISIBLE	Window is initially visible.

WS_VSCROLL	Window has a vertical scroll bar.


See Also

TWindow::IsWindowVisible


TWindowAttr::X, Y, W, H

TWindowAttr struct

Syntax

int X, Y, W, H;

Description

Xand Y contain the screen coordinates of the top left corner of the window. W and H contain the width and height values of the window.


TWindowFlag enum

See Also

Header File

window.h

Syntax

enum TWindowFlag{wfAlias, wfAutoCreate, wfDeleteOnClose, wfFromResource, wfShrinkToClient, wfMainWindow, wfFullyCreated, wfStreamTop, wfPredefinedClass, wfTransfer, wfUnHidden, wfUnDisabled};

Define bit masks for the internally used flag attributes of TWindow. A wfXxxx mask is defined for each of these attributes:

TWindow attribute masks

Constant	Meaning if set

wfAlias	The window object is an alias for an existing HWND.

wfAutoCreate	Create the HWindow when the parent window is created.

wfDeleteOnClose	Indicates that a modeless dialog's pointer is to be deleted when it receives a WM_CLOSE message, causing its class's destructor to be called immediately. Default behavior is to leave the dialog pointer alone. Setting this flag has no effect on modal dialogs. To set this flag for a modeless dialog object, add the following statement to the constructor of your TDialog-derived class:

SetFlag(wfDeleteOnClose);

wfFullyCreated	Window is fully created and not being destroyed.

wfFromResource	HWindow comes from an HWND created from a resource definition.

wfMainWindow	Window is a main window.

wfPredefinedClass	The window belongs to a predefined Windows class, not an ObjectWindows class.

wfShrinkToClient	Tells a frame window to shrink itself to fit around the client window.

wfStreamTop	Indicates the topmost window of the collection of windows to be streamed.

wfTransfer	Participates in the Transfer mechanism.

wfUnDisabled	Temporarily used when an MDI child window is destroyed.

wfUnHidden	Temporarily used when an MDI child window is destroyed.


See Also

TWindow::CreateChildren

TWindow::EnableAutoCreate


TWindow class

OWL Hierarchy	Inheritance

Header File

window.h

Description

TWindow, derived from TEventHandler and TStreamableBase, provides window-specific behavior and encapsulates many functions that control window behavior and specify window creation and registration attributes.

TWindow is a generic window that can be resized and moved. You can construct an instance of TWindow, though normally you use TWindow as a base for your specialized window classes. In general, to associate and disassociate a TWindow object with a window element, you need to follow these steps:

1.	Construct an instance of a TWindow.

2.	Call Create or Execute, which creates the interface element (HWND) and then calls SetupWindow, which calls the base SetupWindow for normal processing, which in turn involves

Creating the HWindow and any child HWindows.

Calling TransferData to setup the transfer of data between the parent and child windows.

3.	To destroy the interface element, choose one of the following actions, depending on your application:

Call Destroy to destroy the interface element unconditionally.

Call CloseWindow, which calls CanClose to test if it is OK to destroy the interface element.

4.	There are two ways to destroy the interface object:

If the object has been new'd, use delete.

If the object has not been new'd, the compiler automatically destructs the object.

The ObjectWindows destroy process consists of two parts: (1) call Destroy to destroy the interface element and (2) then delete the C++ object. However, it is perfectly valid to call Destroy on the interface element without deleting the C++ object and then to call Create at a later time to re-create the window. Because it is also valid to construct a C++ window object on the stack or as an aggregated member, the Destroy function cannot assume it should delete the C++ object.

The user-generated WM_CLOSE event handler, EvClose, also causes a C++ object to be deleted by passing the this pointer to the application. The C++ object is deleted automatically because the EvClose event frequently occurs in response to a user action, and this is the most convenient place for the deletion to take place. Later, when it's safe to do so, the application then deletes the window pointer. Because the stack often contains selectors that refer to the addresses of objects that may become invalid during the delete process, it is not safe to delete the this pointer while events are still being processed. If the addresses become invalid, they could cause trouble when they are reloaded from the stack.

TWindow is the base class for all window classes, including TFrameWindow, TControl, TDialog, and TMDIChild. The ObjectWindows hierarchy diagram shows the many classes that are derived from TWindow.

Public Data Members

TWindowAttr Attr;

WNDPROC DefaultProc;

HWND HWindow;

TWindow* Parent;

TScroller* Scroller;

TStatus Status;

char far* Title;

Public Constructors and Destructor

TWindow(HWND hWnd, TModule* module = 0);

TWindow(TWindow* parent, const char far* title = 0, TModule* module = 0);

virtual ~TWindow();

Public Member Functions

static void AdjustWindowRect(TRect& rect, uint32 style, bool menu);

static void AdjustWindowRectEx(TRect&, rect, uint32 style, bool menu, uint32 exStyle);

void BringWindowToTop();

virtual bool CanClose();

void CheckDlgButton(int buttonId, uint check);

void CheckRadioButton(int firstButtonId, int lastButtonId, int checkButtonId);

void ChildBroadcastMessage(uint msg, WPARAM wParam, LPARAM lParam);

HWND ChildWindowFromPoint(const TPoint&) const;

TWindow* ChildWithId(int id) const;

void ClearFlag(TWindowFlag mask);

void ClientToScreen(TPoint& point) const;

virtual void CloseWindow(int retval = 0);

void CmExit();

virtual bool Create();

void CreateCaret(HBITMAP hBitmap);

void CreateCaret(bool isGray, int width, int height);

bool CreateChildren();

LRESULT DefaultProcessing();

virtual LRESULT DefWindowProc(uint msg, WPARAM wParam, LPARAM lParam);

virtual void Destroy(int retVal = 0);

static void DestroyCaret();

void DisableAutoCreate();

void DisableTransfer();

virtual LRESULT Dispatch(TEventInfo& info, WPARAM wp, LPARAM lp = 0);

void DragAcceptFiles(bool accept);

void DrawMenuBar();

void EnableAutoCreate();

void EnableScrollBar(uint sbFlags = SB_BOTH, uint arrowFlags = ESB_ENABLE_BOTH);

void EnableTransfer();

virtual bool EnableWindow(bool enable);

int EnumProps(PROPENUMPROC proc);

void EvChildInvalid(HWND hWnd);

virtual LRESULT EvCommand(uint id, HWND hWndCtl, uint notifyCode);

void EvCommandEnable(TCommandEnabler& ce);

void EvSysCommand (uint cmdType, TPoint& point);

TWindow* FirstThat(TCondFunc test, void* paramList = 0);

TWindow* FirstThat(TCondMemFunc test, void* paramList = 0);

bool FlashWindow(bool invert);

void ForEach(TActionFunc action, void* paramList = 0);

void ForEach(TActionMemFunc action, void* paramList = 0);

LRESULT ForwardMessage(bool send = true)

LRESULT ForwardMessage(HWND hWnd, bool send = true);

static HWND GetActiveWindow();

TApplication* GetApplication()const;

static HWND GetCapture();

static uint GetCaretBlinkTime();

static void GetCaretPos(TPoint& point);

long GetClassLong(int index) const;

uint16 GetClassWord(int index) const;

TRect GetClientRect() const;

void GetClientRect(TRect& rect) const;

static void GetCursorPos(TPoint& pos);

static HWND GetDesktopWindow;

int GetDlgCtrlID() const;

HWND GetDlgItem(int childId) const;

uint GetDlgItemInt(int childId, bool *translated = 0,bool isSigned = true) const;

uint GetDlgItemText(int childId, char far* text, int max) const;

TWindow* GetFirstChild()

static HWND GetFocus()

void GetHWndState();

int GetId();

TModule* GetModule() const;

HWND GetLastActivePopup() const;

TWindow* GetLastChild();

HMENU GetMenu() const;

HWND GetNextDlgGroupItem(HWND hWndCtrl, bool previous = false) const;

HWND GetNextDlgTabItem(HWND HWndCtrl, bool previous = false) const;

HWND GetNextWindow(uint dirFlag) const;

TWindow* GetWindowPtr(HWND hWnd);

HWND GetParent() const;

HANDLE GetProp(uint16 atom) const;

HANDLE GetProp(const char far* string) const;

int GetScrollPos(int bar) const;

void GetScrollRange(int bar, int& minPos, int& maxPos) const;

static HWND GetSysModalWindow();

HMENU GetSystemMenu(bool revert = false) const;

WNDPROC GetThunk()const;

HWND GetTopWindow()const;

bool GetUpdateRect(TRect& rect, bool erase = true) const;

bool GetUpdateRgn(TRegion& rgn, bool erase = true) const;

HWND GetWindow(uint cmd) const;

HFONT GetWindowFont();

long GetWindowLong(int index) const;

bool GetWindowPlacement(WINDOWPLACEMENT* place) const;

void GetWindowRect(TRect& rect) const;

TRect GetWindowRect() const;

HTASK GetWindowTask() const;

int GetWindowText(char far* string, int maxCount) const;

int GetWindowTextLength() const;

void GetWindowTextTitle();

uint16 GetWindowWord(int index) const;

LRESULT HandleMessage(uint msg, WPARAM wParam = 0, LPARAM lParam = 0);

void HideCaret();

bool HiliteMenuItem(HMENU hMenu, uint idItem, uint hilite);

virtual bool HoldFocusHWnd(HWND hWndLose, HWND hWndGain);

operator HWND()const;

virtual bool IdleAction(long idleCount);

void Invalidate(bool erase = true);

void InvalidateRect(const TRect&, bool erase = true);

void InvalidateRgn(HRGN hRgn, bool erase = true);

bool IsChild(HWND) const;

uint IsDlgButtonChecked(int buttonId) const;

bool IsFlagSet(TWindowFlag mask);

bool IsIconic() const;

bool IsWindow() const;

bool IsWindowEnabled() const;

bool IsWindowVisible() const;

bool IsZoomed() const;

bool KillTimer(uint timerId);

bool LockWindowUpdate();

void MapWindowPoints(HWND hWndTo, TPoint* points, int count) const;

int MessageBox(const char far* text,const char far* caption = 0, uint type = MB_OK);

void MoveWindow(int x, int y, int w, int h, bool repaint = false);

void MoveWindow(const TRect& rect, bool repaint = false);

TWindow* Next();

unsigned NumChildren();

TClipboard& OpenClipboard();

virtual void Paint(TDC& dc, bool erase, TRect& rect);

bool PostMessage(uint msg, WPARAM wParam = 0, LPARAM lParam=0) const;

virtual void PerformCreate(int menuOrId);

virtual bool PreProcessMsg(MSG& msg);

TWindow* Previous();

LRESULT ReceiveMessage(uint msg, WPARAM wParam = 0, LPARAM lParam = 0);

bool RedrawWindow(TRect* update, HRGN hUpdateRgn, uint redrawFlags = RDW_INVALIDATE | RDW_UPDATENOW | RDW_ERASE);

virtual bool Register();

bool RegisterHotKey(int idHotKey, uint modifiers, uint virtKey);

static void ReleaseCapture();

HANDLE RemoveProp(uint16 atom) const;

HANDLE RemoveProp(const char far* str) const;

void RouteCommandEnable(HWND hInitCmdTarget, TCommandEnabler& ce);

void ScreenToClient(TPoint& point) const;

void ScrollWindow(int dx, int dy, const TRect* scroll = 0, const TRect far* clip = 0);

void ScrollWindowEx(int dx, int dy, const TRect far* scroll = 0, const TRect far* clip = 0, HRGN hUpdateRgn = 0, TRect far* update = 0, uint flags = 0);

LRESULT SendDlgItemMessage(int childId, uint msg, WPARAM wParam = 0, LPARAM lParam = 0);

LRESULT SendMessage(uint msg, WPARAM wParam = 0, LPARAM lParam = 0);

void SendNotification(int id, int notifyCode, HWND hCtl, uint msg = WM_COMMAND);

HWND SetActiveWindow();

void SetBkgndColor(uint32 color);

void SetCaption(const char far* title);

HWND SetCapture();

static void SetCaretBlinkTime(uint16 milliSecs);

static void SetCaretPos(int x, int y);

static void SetCaretPos(const TPoint& pos);

long SetClassLong(int index) const;

uint16 SetClassWord(int index, uint16 newWord);

bool SetCursor(TModule* module, TResId resId);

void SetDlgItemInt(int childId, uint value, bool isSigned = true) const;

void SetDlgItemText(int childId, const char far* text) const;

virtual bool SetDocTitle(const char far* docname, int index);

void SetFlag(TWindowFlag mask);

HWND SetFocus();

bool SetMenu(HMENU hMenu);

void SetModule(TModule* module);

void SetNext(TWindow* next);

virtual void SetParent(TWindow* newParent);

bool SetProp(uint16 atom, HANDLE data) const;

bool SetProp(const char far* str, HANDLE data) const;

void SetRedraw(bool redraw);

int SetScrollPos(int bar, int pos, bool redraw = true);

void SetScrollRange(int bar, int minPos, int maxPos, bool redraw = true);

HWND SetSysModalWindow();

uint SetTimer(uint timerId, uint timeout, TIMERPROC proc = 0);

void SetTransferBuffer(void* transferBuffer);

void SetWindowFont(HFONT font, bool redraw);

long SetWindowLong(int index, long newLong);

bool SetWindowPlacement(const WINDOWPLACEMENT* place);

void SetWindowPos(HWND hWndInsertAfter, const TRect& rect, uint flags);

void SetWindowPos(HWND hWndInsertAfter, int x, int y, int w, int h, uint flags);

void SetWindowText(const char far* str);

uint16 SetWindowWord(int index, uint16 newWord);

void Show(int cmdShow);

void ShowCaret();

void ShowOwnedPopups(bool show);

void ShowScrollBar(int bar, bool show = true);

virtual bool ShowWindow(int cmdShow);

void ShutDownWindow(int retVal = 0);

static void ShutDownWindow(TWindow* win, int retVal = 0);

void SubclassWindowFunction();

virtual uint Transfer(void* buffer, TTransferDirection direction);

virtual void TransferData(TTransferDirection direction);

bool UnregisterHotKey(int idHotKey);

void UpdateWindow();

void Validate();

void ValidateRect(const TRect& rect);

void ValidateRgn(HRGN hRgn);

static HWND WindowFromPoint(const TPoint& point) const;

virtual LRESULT WindowProc(uint msg, WPARAM wParam, LPARAM lParam);

bool WinHelp(const char far* helpFile, uint command, uint32 data);

Protected Data Members

uint32 BkgndColor;

TModule* CursorModule;

TResId CursorResId;

HACCEL hAccel;

HCURSOR HCursor;

void* TransferBuffer;

Protected Constructor

TWindow();

Protected Member Functions

virtual void CleanupWindow();

void DispatchScroll(uint scrollCode, uint thumbPos, HWND hWndCtrl);

virtual char far* GetClassName();

virtual void GetWindowClass(WNDCLASS& wndClass);

void Init(TWindow* parent, const char far* title, TModule* module);

void LoadAcceleratorTable();

void RemoveChild(TWindow* child);

virtual void SetupWindow();

Response Table Entries

EV_ macros and member functions


TWindow::Attr

See Also	TWindow

Syntax

TWindowAttr Attr;

Description

Holds a TWindowAttr structure, which contains the window's creation attributes. These attributes, which  include the window's style, extended style, position, size, menu ID, child window ID, and menu accelerator table ID, are passed to the function that creates the window.


See Also

TWindow::TWindow

TWindow::Create


TWindow::DefaultProc

TWindow

Syntax

WNDPROC DefaultProc;

Description

Holds the address of the default window procedure. DefWindowProc calls DefaultProc to process Windows messages that are not handled by the window.


TWindow::HWindow

TWindow

Syntax

HWND HWindow;

Description

Holds the handle to the associated MS-Windows window, which you'll need to access if you make calls directly to Windows API functions.


TWindow::Parent

TWindow

Syntax

TWindow* Parent;

Description

Points to the interface object that serves as the parent window for this interface object.


TWindow::Scroller

TWindow

Syntax

TScroller* Scroller;

Description

Points to the scroller object that supports either the horizontal or vertical scrolling for this window.


TWindow::Status

TWindow

Syntax

TStatus Status;

Description

Used to signal an error in the initialization of an interface object. Setting Status to a nonzero value causes a TXCompatibility exception to be thrown. Classes derived from TWindow do not attempt to associate an interface element with an object whose previous initialization has failed. Status is included only to provide backward compatibility with previous versions of ObjectWindows.


TWindow::Title

See Also	TWindow

Syntax

char far* Title;

Description

Points to the window's caption. When there is a valid HWindow, Title will yield the same information as ::GetWindowText if you use TWindow::SetCaption to set it.


See Also

::GetWindowText - See Windows API Help.

TDialog::SetCaption

TDialog::SetupWindow

TWindow::GetWindowTextTitle


TWindow Public Constructors and Destructor

See Also	TWindow

Syntax 1

TWindow(HWND hWnd, TModule* module = 0);

Syntax 2

TWindow(TWindow* parent, const char far* title = 0, TModule* module = 0);

Description

Both Forms

The following paragraphs describe procedures common to both constructors. module specifies the application or DLL that owns the TWindow instance. ObjectWindows needs the correct value of module to find needed resources. If module is 0, TWindow sets its module according to the following rules:

If the window has a parent, the parent's module is used.

If the TWindow constructor is invoked from an application, the module is set to the application.

If the TWindow constructor is invoked from a DLL that is dynamically linked with the ObjectWindows DLL and the currently running application is linked the same way, the module is set to the currently running application.

If the TWindow constructor is invoked from a DLL that is statically linked with the ObjectWindows library or the invoking DLL is dynamically linked with ObjectWindows DLL but the currently running application is not, no default is used for setting the module. Instead, a TXInvalidModule exception is thrown and the object is not created.

Form 1: Constructs a TWindow that is used as an alias for a non-ObjectWindows window, and sets wfAlias. Because the HWND is already available, this constructor, unlike the other TWindow constructor, performs the "thunking" and extraction of HWND information instead of waiting until the function Create creates the interface element.

Form 2: Adds this to the child list of parent if nonzero, and calls EnableAutoCreate so that this will be created and displayed along with parent. Also sets the title of the window and initializes the window's creation attributes.

Destructor

virtual ~TWindow();

Description

Destroys a still-associated interface element by calling Destroy. Deletes the window objects in the child list, then removes this from the parent window's child list. Deletes the Scroller if it is nonzero. Frees the cursor, if any exists, and the object instance (thunk).


See Also

TWindowFlag enum

TWindow::EnableAutoCreate


TWindow::AdjustWindowRect

TWindow

Syntax

static void AdjustWindowRect(TRect& rect, uint32 style, bool menu);

Description

Calculates the size of the window rectangle according to the indicated client-rectangle size. rect refers to the structure that contains the client rectangle's coordinates. style specifies the style of the window. menu is true if the window has a menu.


TWindow::AdjustWindowRectEx

See Also	TWindow

Syntax

static void AdjustWindowRectEx(TRect& rect, uint32 style, bool menu, uint32 exStyle);

Description

Calculates the size of a window rectangle that has an extended style. TRect refers to the class that contains the client rectangle's coordinates. style specifies the window styles of the window to be adjusted. menu returns true if the window has a menu. exStyle indicates the extended styles to be used for the window. Extended styles include the following styles:

Value	Meaning

WS_EX_ACCEPTFILES	The window can make use of drag and drop files.

WS_EX_DLGMODALFRAME	The window has a double border that can be created with a title bar if the WS_CAPTION style flag is specified.

WS_EX_NOPARENTNOTIFY	The child window created from this style does not send parent notify messages to the parent window when the child is created or destroyed.

WS_EX_TOPMOST	A window having this style is placed above windows that are not topmost and remains above the non-topmost windows even when it's deactivated.

WS_EX_TRANSPARENT	A window having this style is transparent, that is, any windows beneath this window are not concealed by this window.


See Also

TWindowAttr struct


TWindow::BringWindowToTop

TWindow

Syntax

void BringWindowToTop();

Description

Brings a pop-up or child window to the top of the stack of overlapping windows and activates it.


TWindow::CanClose

TWindow

Syntax

virtual bool CanClose();

Description

Use this function to determine if it is okay to close a window. Returns true if the associated interface element can be closed. Calls the CanClose member function of each of its child windows. Returns false if any of the CanClose calls returns false.

In your application's main window, you can override TWindow's CanClose and call TWindow::MessageBox to display a YESNOCANCEL message prompting the user as follows:

YES 	Save the data

NO 	Do not save the data, but close the window

CANCEL 	Cancel the close operation and return to the edit window

The following example shows how to write a CanClose function that displays a message box asking if the user wants to save a drawing that has changed. To save time, CanClose uses the IsDirty flag to see if the drawing has changed. If so, CanClose queries the user before closing the window.

bool TMyWindow::CanClose()

{

  if (IsDirty)

    switch(MessageBox("Do you want to save?", "Drawing has changed.",

                      MB_YESNOCANCEL | MB_ICONQUESTION)) {

      case IDCANCEL:

        // Choosing Cancel means to abort the close -- return false.

        return false;

      case IDYES:

        // Choosing Yes means to save the drawing.

        CmFileSave();

    }

  return true;

}


TWindow::CheckDlgButton

TWindow

Syntax

void CheckDlgButton(int buttonId, uint check);

Description

Places a check mark in (or removes a check mark from) the button specified in buttonId. If check is nonzero, the check mark is placed next to the button; if 0, the check mark is removed. For buttons having three states, check can be 0 (clear), 1 (checked), or 2 (gray).


TWindow::CheckRadioButton

TWindow

Syntax

void CheckRadioButton(int firstButtonId, int lastButtonId, int checkButtonId);

Description

Checks the radio button specified by checkButtonId and removes the check mark from the other radio buttons in the group. firstButtonId and lastButtonId specify the first and last buttons, respectively, in the group.


TWindow::ChildBroadcastMessage

See Also	TWindow

Syntax

void ChildBroadcastMessage(uint msg, WPARAM wParam, LPARAM lParam);

Description

Sends the specified message to all immediate children using SendMessage.


See Also

TWindow::SendMessage


TWindow::ChildWindowFromPoint

See Also	TWindow

Syntax

HWND ChildWindowFromPoint(const TPoint&) const;

Description

Determines which of the child windows contains the point specified in TPoint. Returns a handle to the window that contains the point, or 0 if the point lies outside the parent window.


See Also

TWindow::WindowFromPoint


TWindow::ChildWithId

TWindow

Syntax

TWindow* ChildWithId(int id) const;

Description

Returns a pointer to the window in the child window list that has the supplied id. Returns 0 if no child window has the indicated id.


TWindow Protected Constructor

TWindow

Syntax

TWindow();

Description

Constructor used with virtually derived classes. Immediate derived classes must call Init before the construction of the object is finished.


TWindow::ClearFlag

See Also	TWindow

Syntax

void ClearFlag(TWindowFlag mask);

Description

Clears the specified TWindow wfXxxx constant flags (for example wfAlias, wfTransfer, and so on) in the Flags member.


See Also

TWindowFlag enum


TWindow::ClientToScreen

TWindow

Syntax

void ClientToScreen(TPoint& point) const;

Description

Converts the client coordinates specified in point to screen coordinates for the new window.


TWindow::CloseWindow

See Also	TWindow

Syntax

virtual void CloseWindow(int retval = 0);

Description

Determines if it is okay to close a window before actually closing the window. If this is the main window of the application, calls GetApplication->CanClose. Otherwise, calls this->CanClose to determine whether the window can be closed. After determining that it is okay to close the window, CloseWindow calls Destroy to destroy the HWND.


See Also

TApplication::CanClose

TWindow::CanClose


TWindow::CmExit

TWindow

Syntax

void CmExit();

Description

Called in response to the selection of a menu item that has an ID of CM_EXIT. If this is the main window, CmExit calls CloseWindow.


TWindow::Create

See Also	TWindow

Syntax

virtual bool Create();

Description

Creates the window interface element to be associated with this ObjectWindows interface element. Specifically, Create performs the following window creation tasks:

1.	If the HWND already exists, Create returns true. (It is perfectly valid to call Create even if the window currently exists.)

2.	If the wfFromResource flag is set, then Create grabs the HWND based on the window ID. Otherwise, Create registers the window, sets up the window thunk, loads accelerators and menus, and calls PerformCreate in the derived class to create the HWND.

3.	If class registration fails for the window, Create calls TXWindow with IDS_CLASSREGISTERFAIL. If the window creation fails, Create calls TXWindow  with IDS_WINDOWCREATEFAIL.

4.	If the window is created for a predefined Window class (for example, a button or dialog class) registered outside of ObjectWindows, then ObjectWindows thunks the window so that it can intercept messages and obtains the state of the window (the window's attributes) from the HWND.


See Also

TWindowFlag enum


TWindow::CreateCaret

TWindow

Syntax 1

void CreateCaret(HBITMAP hBitmap);

Description

Creates a new caret for the system. HBITMAP specifies the bit mapped caret shape.

Syntax 2

void CreateCaret(bool isGray, int width, int height);

Description

Create a new caret for the system with the specified shape, bitmap shade, width, and height. If width or height is 0, the corresponding system-defined border size is used.


TWindow::CreateChildren

See Also	TWindow

Syntax

bool CreateChildren();

Description

Creates the child windows in the child list whose auto-create flags (with wfAutoCreate mask) are set. If all of the child windows are created successfully, CreateChildren returns true.


See Also

TWindow::EnableAutoCreate

TWindow::DisableAutoCreate

TWindowFlag enum


TWindow::DefaultProcessing

See Also	TWindow

Syntax

LRESULT DefaultProcessing();

Description

Serves as a general-purpose default processing function that handles a variety of messages. After being created and before calling DefaultProcessing, however, a window completes the following sequence of events (illustrated in the Default Message-Processing Flowchart).

If the window is already created, SubclassWindow is used to install StdWndProc in place of the window's current procedure. The previous window procedure is saved in DefaultProc.

If the window has not been created, InitWndProc is set up as the window proc in the class. Then, when the window first receives a message, InitWndProc calls GetThunk to get the window's instance thunk (created by the constructor by calling CreateInstanceThunk). InitWndProc then switches the message-receiving capability from the window's procedure to StdWndProc.

After this point, StdWndProc responds to incoming messages by calling the window's virtual WindowProc to process the messages. ObjectWindows uses the special registered message ::GetWindowPtrMsgId to get the this pointer of an HWND. StdWndProc responds to this message by returning the this pointer obtained from the thunk.

If the incoming message is not a command or command enable message, WindowProc immediately searches the window's response table for a matching entry. If the incoming message is a command or command enable message, WindowProc calls EvCommand or EvCommandEnable. EvCommand and EvCommandEnable begin searching for a matching entry in the focus window's response table. If an entry is found, the corresponding function is dispatched; otherwise ObjectWindows calls DefaultProcessing to finish the recursive walk back up the parent chain, searching for a match until the receiving window (the window that initially received the message) is reached. At this point, one of the following actions occurs:

If there is still no match and this is the MainWindow of the application, the window searches the application's response table.

If there are no matches and this is a command, DefWindowProc is called.

If this is a CommandEnable message, no further action is taken.

If this is not a command, and if a response table entry exists for the window, WindowProc dispatches the corresponding EvXxxx function to handle the message.

If this is the application's MainWindow, and the message is designed for the application, the message is forwarded to the application.

For any other cases, the window calls DefWindowProc.

The following diagram illustrates this sequence of message-processing events:


See Also

TWindow::DefWindowProc

TWindow::EnableAutoCreate

TWindow::DisableAutoCreate

TWindow::WindowProc


Default Message Processing Flowchart


TWindow::DefWindowProc

See Also	TWindow

Syntax

virtual LRESULT DefWindowProc(uint msg, WPARAM wParam, LPARAM lParam);

Description

Performs default Windows processing and passes the incoming Windows message. You usually do not need to call this function directly. Classes such as TMDIFrame and TMDIChild override this function to perform specialized default processing.


See Also

TWindow::DefaultProc

TWindow::WindowProc


TWindow::Destroy

TWindow

Syntax

virtual void Destroy(int retVal = 0);

Description

First, Destroy calls EnableAutoCreate for each window in the child list to ensure that windows in the child list will be re-created if this is re-created. Then, it destroys the associated interface element.

If a derived window class expects to be destructed directly, it should call Destroy as the first step in its destruction so that any virtual functions and event handlers can be called during the destroy sequence.


TWindow::DestroyCaret

See Also	TWindow

Syntax

static void DestroyCaret();

Description

DestroyCaret first checks the ownership of the caret. If a window in the current task owns the caret, DestroyCaret destroys the caret and removes it from the screen.


See Also

TWindow::CreateCaret


TWindow::DisableAutoCreate

See Also	TWindow

Syntax

void DisableAutoCreate();

Description

Disables the feature that allows an associated child window interface element to be created and displayed along with its parent window. Call DisableAutoCreate for pop-up windows and controls if you want to create and display them at a time later than their parent windows.


See Also

TWindow::EnableAutoCreate


TWindow::DisableTransfer

See Also	TWindow

Syntax

void DisableTransfer();

Description

Disables (for the interface object) the transfer mechanism, which allows state data to be transferred to and from a transfer buffer.


See Also

TWindowFlag enum


TWindow::Dispatch

TWindow

Syntax

virtual LRESULT Dispatch(TEventInfo& info, WPARAM wp, LPARAM lp = 0);

Description

 Cracks and dispatches a TWindow  message. The info parameter is the event-handling function. The wp and lp parameters are the message parameters the dispatcher cracks.


TWindow::DragAcceptFiles

TWindow

Syntax

void DragAcceptFiles(bool accept);

Description

If a window can process dropped files, DragAcceptFiles sets accept to true.


TWindow::DrawMenuBar

TWindow

Syntax

void DrawMenuBar();

Description

DrawMenuBar redraws the menu bar. This function should be called to redraw the menu if the menu is changed after the window is created.


TWindow::EnableAutoCreate

See Also	TWindow

Syntax

void EnableAutoCreate();

Description

Ensures that an associated child window interface element is created and displayed along with its parent window. By default, this feature is enabled for windows and controls, but disabled for dialog boxes.


See Also

TWindow::DisableAutoCreate


TWindow::EnableScrollBar

See Also	TWindow

Syntax

void EnableScrollBar(uint sbFlags = SB_BOTH, uint arrowFlags = ESB_ENABLE_BOTH);

Description

 Disables or enables one or both of the scroll bar arrows on the scroll bars associated with this window. sbFlags, which specifies the type of scroll bar, can be one of the Scroll Bar constants (SB_CTL, SB_HORZ, SB_VERT, or SB_BOTH). By default, the arrows on both the horizontal and vertical scroll bars are either enabled or disabled. arrowFlags, which indicates whether the scroll bar arrows are enabled or disabled, can be one of the Enable Scroll Bar constants (ESB_ENABLE_BOTH, ESB_DISABLE_LTUP, ESB_DISABLE_RTDN, ESB_DISABLE_BOTH). By default, the arrows on both the horizontal and vertical scroll bars are enabled.


See Also

SB_Xxxx ScrollBar Constants


TWindow::EnableTransfer

TWindow

Syntax

void EnableTransfer();

Description

Enables the transfer mechanism, which allows state data to be transferred between the window and a transfer buffer.


TWindow::EnableWindow

TWindow

Syntax

virtual bool EnableWindow(bool enable);

Description

Allows the given window to receive input from the keyboard of mouse. If enable is true, the window can receive input. Use the function IsWindowEnabled to determine if the window has been enabled.


TWindow::EnumProps

TWindow

Syntax

int EnumProps(PROPENUMPROC proc);

Description

Enumerates all the items in the property list of the current window and passes them one by one to the callback function indicated in proc. The process continues until every item has been enumerated or until proc returns zero. proc holds the address of the callback function.


TWindow::EvChildInvalid

TWindow

Syntax

void EvChildInvalid(HWND hWnd);

Description

Responds to a WM_CHILDINVALID message posted by a child edit control. Indicates that the contents of the child window are invalid.


TWindow::EvCommand

See Also	TWindow

Syntax

virtual LRESULT EvCommand(uint id, HWND hWndCtl, uint notifyCode);

Description

WindowProc calls EvCommand to handle WM_COMMAND messages. id is the identifier of the menu item or control. hWndCtl holds a value that represents the control sending the message. If the message is not from a control, it is 0. notifyCode holds a value that represents the control's notification message. If the message is from an accelerator, notifyCode is 1; if the message is from a menu, notifyCode is 0.


See Also

TWindow::DefaultProcessing


TWindow::EvCommandEnable

See Also	TWindow

Syntax

virtual void EvCommandEnable(TCommandEnabler& ce);

Description

Called by WindowProc to handle WM_COMMAND_ENABLE messages, EvCommandEnable calls the CmXxxx command-handling function or calls DefaultProcessing to handle the incoming message.


See Also

TCommandEnabler


TWindow::EvSysCommand

TWindow

Syntax

void EvSysCommand(uint cmdType, TPoint& point);

Description

Responds to a user-selected command from the System menu or when the user selects the maximize or minimize box. Applications that modify the system menu must process EvSysCommand messages. Any EvSysCommand messages not handled by the application must be passed to DefaultProcessing. The parameter cmdType can be one of the following system commands:

Constant	Meaning

SC_CLOSE	Close the window.

SC_HOTKEY	Activate the specified window.

SC_HSCROLL	Scroll horizontally.

SC_KEYMENU	Retrieve a menu through a keystroke.

SC_MAXIMIZE (or SC_ZOOM)	Maximize the window.

SC_MINIMIZE (or SC_ICON)	Minimize the window.

SC_MOUSEMENU	Retrieve a menu through a mouse click.

SC_NEXTWINDOW	Move to the next window.

SC_PREVWINDOW	Move to the previous window.

SC_SCREENSAVE	Execute the specified screen saver.

SC_SIZE	Size the window

SC_TASKLIST	Activate the Windows Task Manager.

SC_VSCROLL	Scroll vertically.

In the following example, EvSysCommand either processes system messages or calls DefaultProcessing:

void MyWindow::EvSysCommand(uint cmdType, TPoint&)

{

   switch (cmdType&  0xFFF0) {

      case SC_MOUSEMENU:

      case SC_KEYMENU:

         break;

      default:

         DefaultProcessing();

}

}


TWindow::FirstThat

See Also	TWindow

Syntax

TWindow* FirstThat(TCondFunc test, void* paramList = 0);

TWindow* FirstThat(TCondMemFunc test, void* paramList = 0);

Description

There are two FirstThat functions, both of which pass a pointer to an iterator function. The first FirstThat points to a nonmember function as its first parameter; the second FirstThat points to a member function instead.

Both FirstThat functions iterate over the child list, calling a Boolean test function and passing each child window in turn as an argument (along with paramList). If a test call returns true, the iteration is stopped and FirstThat returns the child window object that was supplied to test. Otherwise, FirstThat returns 0.

In the following example, GetFirstChecked calls FirstThat to obtain a pointer (p) to the first check box in the child list that is checked:

bool IsThisBoxChecked(TWindow* p, void*) {

   return ((TCheckBox*)p)->GetCheck() == BF_CHECKED;

}

TCheckBox* TMyWindow::GetFirstChecked() {

   return FirstThat(IsThisBoxChecked);

}


See Also

TCondFunc type


TWindow::FlashWindow

TWindow

Syntax

bool FlashWindow(bool invert);

Description

Changes the window from active to inactive or vice versa. If invert is nonzero, the window is flashed. If invert is 0, the window is returned to its original stateeither active or inactive.


TWindow::ForEach

See Also	TWindow

Syntax 1

void ForEach(TActionFunc action, void* paramList = 0);

Description

Form 1: There are two ForEach functions. This ForEach takes a nonmember function as its first parameter; the other ForEach (see the following entry) takes a member function instead. This version of ForEach iterates over the child list, calling a nonmember function supplied as the action to be performed and passing each child window in turn as the argument (along with paramList).

In the following example, CheckAllBoxes calls ForEach, checking all the check boxes in the child list:

void CheckTheBox(TWindow* p, void*) {

 ((TCheckBox*)p)->Check();

}

void CheckAllBoxes() {

  ForEach(CheckTheBox);

}

Syntax 2

void ForEach(TActionMemFunc action, void* paramList = 0);

Description

Refer to the ForEach description for Syntax 1. The difference between the two ForEach members is that the first ForEach takes a nonmember function as a parameter and this ForEach takes a member function as a parameter.


See Also

TActionFunc typedef

TActionMemFunc typedef


TWindow::ForwardMessage

TWindow

Syntax 1

LRESULT ForwardMessage(bool send = true)

Description

Forwards the window's current message. Calls SendMessage if send is true; otherwise calls PostMessage.

Syntax 2

LRESULT ForwardMessage(HWND hWnd, bool send = true);

Description

Forwards the window's current message to another HWND. Calls SendMessage if send is true; otherwise calls PostMessage.


TWindow::GetActiveWindow

TWindow

Syntax

static HWND GetActiveWindow();

Description

Retrieves the handle of the active window. Returns 0 if no window is associated with the calling thread.


TWindow::GetApplication

TWindow

Syntax

TApplication* GetApplication()const;

Description

Gets a pointer to the TApplication object associated with this. Use GetApplication to obtain access to data and functions in the TApplication object.


TWindow::GetCapture

TWindow

Syntax

static HWND GetCapture();

Description

Returns the handle of the window that has captured the mouse.


TWindow::GetCaretBlinkTime

See Also	TWindow

Syntax

static uint GetCaretBlinkTime();

Description

Retrieves the caret blink rate in milliseconds.


See Also

TWindow::SetCaretBlinkTime


TWindow::GetCaretPos

See Also	TWindow

Syntax

static void GetCaretPos(TPoint& point);

Description

Gets the position of the caret in the coordinates of the client window. point refers to the structure that receives the client coordinates of the caret.


See Also

TWindow::SetCaretPos


TWindow::GetClassLong

See Also	TWindow

Syntax

long GetClassLong(int index) const;

Description

Retrieves the 32-bit value containing information about the window class. If unsuccessful, returns 0.  Depending on the value of index, GetClassLong can retrieve the following information:

Value	Meaning

GCL_CBCLSEXTRA	Size in bytes of memory associated with this class

GCL_CBWINDEXTRA	Size of extra window memory associated with each window

GCL_HBRBACKGROUND	Handle of the background brush associated with the class

GCL_HCURSOR	Handle of the cursor

GCL_HICON	Handle of the icon

GCL_HMODULE	Handle of the module that registered the class

GCL_MENUNAME	Address of the menu name string

GCL_STYLE	The style bits associated with a window class

GCL_WNDPROC	Address of the window procedure associated with this class


See Also

Twindow::SetClassLong


TWindow::GetClassWord

See Also	TWindow

Syntax

uint16 GetClassWord(int index) const;

Description

Gets a 16-bit value containing information about the class or style of the window. If unsuccessful; returns 0. Depending on the value of index, GetClassWord can retrieve the following information:

Value	Meaning

GCW_CBCLSEXTRA	Number of additional class information

GCW_CBWINDEXTRA	Number of bytes of additional window information

GCW_HBRBACKGROUND	Handle of the background brush

GCW_HCURSOR	Handle of the cursor

GCW_HICON	Handle of the icon

GCW_HMODULE	Handle of the module

GCW_STYLE	The style bits associated with a window class


See Also

TWindow::SetClassWord


TWindow::GetClientRect

TWindow

Syntax 1

TRect GetClientRect() const;

Description

Gets the coordinates of the window's client area (the area in a window you can use for drawing).

Form 2

void GetClientRect(TRect& rect) const;

Description

Gets the coordinates of the window's client area and then copies them into the object referred to by TRect.


TWindow::GetCursorPos

TWindow

Syntax

static void GetCursorPos(TPoint& pos);

Description

Retrieves the cursor's current position (in window screen coordinates) and copies the values into the structure pointed to by pos.


TWindow::GetDesktopWindow

TWindow

Syntax

static HWND GetDesktopWindow();

Description

Returns a handle to the desktop window.


TWindow::GetDlgCtrlID

TWindow

Syntax

int GetDlgCtrlID() const;

Description

Returns the ID of the control.


TWindow::GetDlgItem

See Also	TWindow

Syntax

HWND GetDlgItem(int childId) const;

Description

Retrieves the handle of a control specified by childId.


See Also

TWindow::GetDlgItemInt


TWindow::GetDlgItemInt

See Also	TWindow

Syntax

uint GetDlgItemInt(int childId, bool *translated = 0,bool isSigned = true) const;

Description

Retrieves the text of a control specified by childId. translated points to the variable that receives the translated value. isSigned indicates that the retrieved value is signed (the default).


See Also

TWindow::GetDlgItem


TWindow::GetDlgItemText

See Also	TWindow

Syntax

uint GetDlgItemText(int childId, char far* text, int max) const;

Description

Retrieves the text of a control specified by childId. text points to the text buffer to receive the text. max specifies the maximum length of the caption, which is truncated if it exceeds this length.


See Also

TWindow::SetDlgItemText


TWindow::GetFirstChild

See Also	TWindow

Syntax

TWindow* GetFirstChild()

Description

Returns a pointer to the first child window, which is the first window created in the interface object's child list.


See Also

TWindowAttr struc


TWindow::GetFocus

TWindow

Syntax

static HWND GetFocus();

Description

Gets a handle to the window that has the focus. Use the function SetFocus to set the keyboard focus to this window.


TWindow::GetHWndState

TWindow

Syntax

void GetHWndState();

Description

Copies the style, coordinate, and the resource id (but not the title) from the existing HWnd into the TWindow members.


TWindow::GetId

See Also	TWindow

Syntax

int GetId();

Description

Returns Attr.Id, the ID used to find the window in a specified parent's child list.


See Also

TWindowAttr struct


TWindow::GetModule

TWindow

Syntax

TModule* GetModule() const;

Description

Returns a pointer to the module object.


TWindow::GetLastActivePopup

TWindow

Syntax

HWND GetLastActivePopup() const;

Description

Returns the last active pop-up window in the list.


TWindow::GetLastChild

TWindow

Syntax

TWindow* GetLastChild();

Description

Returns a pointer to the last child window in the interface object's child list.


TWindow::GetMenu

See Also	TWindow

Syntax

HMENU GetMenu() const;

Description

 Returns the handle to the menu of the indicated window. If the window has no menu, the return value is 0.


See Also

TWindow::SetMenu


TWindow::GetNextDlgGroupItem

TWindow

Syntax

HWND GetNextDlgGroupItem(HWND hWndCtrl, bool previous = false) const;

Description

Returns either the next or the previous control in the dialog box. hWndCtrl identifies the control in the dialog box where the search begins. If previous is 0, GetNextDlgGroupItem searches for the next control. If previous is nonzero, it searches for the previous control.


TWindow::GetNextDlgTabItem

TWindow

Syntax

HWND GetNextDlgTabItem(HWND HWndCtrl, bool previous = false) const;

Description

Returns the handle of the first control that lets the user press the Tab key to move to the next control (that is, the first control with the WS_TABSTOP style associated with it). hWndCtrl identifies the control in the dialog box where the search begins. If previous is 0, GetNextDlgTabItem searches for the next control. If previous is nonzero, it searches for the previous control.


TWindow::GetNextWindow

TWindow

Syntax

HWND GetNextWindow(uint dirFlag) const;

Description

Finds the handle associated with either the next or previous window in the window manager's list. dirFlag specifies the direction of the search. Under the Win 32 API, GetNextWindow returns either the next or the previous window's handle. If the application is not running under Win32, GetNextWindow returns the next window's handle.


TWindow::GetWindowPtr

TWindow

Syntax

TWindow* GetWindowPtr(HWND hWnd);

Description

Calls TApplication:GetWindowPtr on the application associated with this window. Then, given the handle to this window (hWnd), GetWindowPtr returns the TWindow pointer associated with this window.


TWindow::GetParent

See Also	TWindow

Syntax

HWND GetParent() const;

Description

Retrieves the handle of the parent window. If none exists, returns 0.


See Also

TWindow::SetParent


TWindow::GetProp

See Also	TWindow

Syntax 1

HANDLE GetProp(uint16 atom) const;

Description

Returns a handle to the property list of the specified window. atom contains a value that identifies the character string whose handle is to be retrieved. If the specified string is not found in the property list for this window, returns NULL.

Syntax 2

HANDLE GetProp(const char far* string) const;

Description

Returns a handle to the property list of the specified window. Unlike the Syntax 1 GetProp function, string points to the string whose handle is to be retrieved. If the specified string is not found in the property list for this window, returns NULL.


See Also

TWindow::SetProp


TWindow::GetScrollPos

See Also	TWindow

Syntax

int GetScrollPos(int bar) const;

Description

Returns the thumb position in the scroll bar. The position returned is relative to the scrolling range. If bar is SB_CTL, it returns the position of a control in the scroll bar. If bar is SB_HORZ, it returns the position of a horizontal scroll bar. If bar is SB_VERT, it returns the position of a vertical scroll bar.


See Also

TWindow::SetScrollPos

SB_Xxxx Scroll Bar Constants


TWindow::GetScrollRange

See Also	TWindow

Syntax

void GetScrollRange(int bar, int& minPos, int& maxPos) const;

Description

Returns the minimum and maximum positions in the scroll bar. If bar is SB_CTL, it returns the position of a control in the scroll bar. If bar is SB_HORZ, it returns the position of a horizontal scroll bar. If bar is SB_VERT, it returns the position of a vertical scroll bar. minPos and maxPos hold the lower and upper range, respectively, of the scroll bar positions. If there are no scroll bar controls or if the scrolls are non-standard, minPos and maxPos are zero.


See Also

TWindow::SetScrollRange

SB_Xxxx Scroll Bar Constants


TWindow::GetSysModalWindow

See Also	TWindow

Syntax

static HWND GetSysModalWindow();

Description

Retrieves the handle of the system-modal window.


See Also

TWindow::SetSysModalWindow


TWindow::GetSystemMenu

TWindow

Syntax

HMENU GetSystemMenu(bool revert = false) const;

Description

Returns a handle to the system menu so that an application can access the system menu.


TWindow::GetThunk

TWindow

Syntax

WNDPROC GetThunk()const;

Description

Gets the instance thunk, a small piece of code created for use with exported callback functions.


A function that exists within a program but is called from outside the program by a Windows library routine; for example, a dialog box function


TWindow::GetTopWindow

TWindow

Syntax

HWND GetTopWindow()const;

Description

Returns a handle to the top window currently owned by this parent window. If no children exist, GetTopWindow returns 0.


TWindow::GetUpdateRect

See Also	TWindow

Syntax

bool GetUpdateRect(TRect& rect, bool erase = true) const;

Description

Retrieves the screen coordinates of the rectangle that encloses the updated region of the specified window. erase specifies whether GetUpdateRect should erase the background of the updated region.


See Also

TWindow::RedrawWindow


TWindow::GetUpdateRgn

See Also	TWindow

Syntax

bool GetUpdateRgn(TRegion& rgn, bool erase = true) const;

Description

Copies a window's update region into a region specified by region. If erase is true, GetUpdateRgn erases the background of the updated region and redraws nonclient regions of any child windows. If erase is false, no redrawing occurs.

If the call is successful, GetUpdateRgn returns a value indicating the kind of region that was updated. If the region has no overlapping borders, it returns SIMPLEREGION; if the region has overlapping borders, it returns COMPLEXREGION; if the region is empty, it returns NULLREGION; if an error occurs, it returns ERROR.


See Also

TWindow::RedrawWindow


TWindow::GetWindow

TWindow

Syntax

HWND GetWindow (uint cmd) const;

Description

Returns the handle of the window that has the indicated relationship to this window.  cmd, which indicates the type of relationship to be obtained, can be one of the following values:

Value	Meaning

GW_CHILD	If the given window is a parent window, the return value indicates the child window at the top of the Z order (the position of a window in a series of overlapping windows arranged in a stack). Otherwise, the return value is 0. Only child windows are examined.

GW_HWNDFIRST	The return value indicates the window at the top of the Z order. If this window is a topmost window, the return value identifies the topmost window at the top of the Z order. If this window is a top-level window, the return value identifies the top-level window at the bottom of the Z order. If this window is a child window, the return value indicates the sibling window at the bottom of the Z order.

GW_HWNDNEXT	The return value identifies the window below the given window in the Z order. If this window is a topmost window, the return value identifies the topmost window below this window. If this window is a top-level window, the return value indicates the top-level window below this window. If this window is a child window, the return value indicates the sibling window below this window.

GW_HWNDPREV	The return value identifies the window above the given window in the Z order. If this window is a topmost window, the return value identifies the topmost window above this window. If this window is a top-level window, the return value indicates the top-level window above this window. If this window is a child window, the return value indicates the sibling window above this window.

GW_OWNER	The return value identifies this window's owner window, if one exists.


TWindow::GetWindowFont

TWindow

Syntax

HFONT GetWindowFont();

Description

Gets the font the control uses to draw text. The return value is a handle of the font the control uses. If a system default font is being used, GetWindowFont  returns NULL.


TWindow::GetWindowLong

See Also	TWindow

Syntax

long GetWindowLong(int index) const;

Description

Retrieves information about the window depending on the value stored in index. The values returned, which provide information about the window, include the following GWL_Xxxx window style constants:

Value	Description

GWL_EXSTYLE 	The extended window style

GWL_STYLE	The window style (position, device context creation, size, and so on)

GWL_WNDPROC  	The address of the window procedure being processed

In the case of a dialog box, additional information can be retrieved, such as:

Value	Description

DWL_DLGPROC 	The address of the procedure processed by the dialog box

DWL_MSGRESULT 	The value that a message processed by the dialog box returns

DWL_USER	Additional information that pertains to the application, such as pointers or handles the application uses.


See Also

TWindow::GetClassLong


TWindow::GetWindowPlacement

See Also	TWindow

Syntax

bool GetWindowPlacement(WINDOWPLACEMENT* place) const;

Description

Retrieves display and placement information (normal, minimized, and maximized positions) about the window and stores that information in the argument, place.


See Also

TWindow::SetWindowPlacement

TWindow::Show


TWindow::GetWindowRect

See Also	TWindow

Syntax 1

void GetWindowRect(Trect& rect) const;

Description

Gets the screen coordinates of the window's rectangle and copies them into rect.

Syntax 2

TRect GetWindowRect() const;

Description

Gets the screen coordinates of the window's rectangle.


See Also

TWindow::GetClientRect


TWindow::GetWindowTask

TWindow

Syntax

HTASK GetWindowTask() const;

Description

 Returns a handle to the task that created the specified window.


TWindow::GetWindowText

See Also	TWindow

Syntax

int GetWindowText(char far* string, int maxCount) const;

Description

Copies the window's title into a buffer pointed to by string. maxCount indicates the maximum number of characters to copy into the buffer. A string of characters longer than maxCount is truncated. GetWindowText returns the length of the string or 0 if no title exists.


See Also

TWindow::SetWindowText

TWindow::GetWindowTextTitle

TWindow::SetCaption


TWindow::GetWindowTextLength

See Also	TWindow

Syntax

int GetWindowTextLength() const;

Description

Returns the length, in characters, of the specified window's title. If the window is a control, returns the length of the text within the control. If the window does not contain any text, GetWindowTextLength returns 0.


See Also

TWindow::SetWindowText


TWindow::GetWindowTextTitle

See Also	TWindow

Syntax

void GetWindowTextTitle();

Description

Updates the TWindow title data member (Title) from the current window's caption. GetWindowTextTitle is used to keep Title synchronized with the actual window state when there is a possibility that the state might have changed.


See Also

TWindow::SetCaption

TWindow::Title


TWindow::GetWindowWord

See Also	TWindow

Syntax

uint16 GetWindowWord(int index) const;

Description

Retrieves information about this window depending on the value of index. GetWindowWord returns one of the following values that indicate information about the window:

Value	Meaning

GWW_HINSTANCE	The instance handle of the module owning the window

GWW_HWNDPARENT	The handle of the parent window

GWW_ID	The ID number of the child window


See Also

TWindow::GetWindowLong

TWindow::SetWindowWord

TWindow::SetParent


TWindow::HandleMessage

TWindow

Syntax

LRESULT HandleMessage(uint msg, WPARAM wParam = 0, LPARAM lParam = 0);

Description

Handles message sent to a window. HandleMessage can be called directly to handle Windows messages without going through SendMessage.


TWindow::HideCaret

See Also	TWindow

Syntax

void HideCaret();

Description

Removes the caret from the specified display screen. The caret is hidden only if the current task's window owns the caret. Although the caret is not visible, it can be displayed again using ShowCaret


See Also

TWindow::CreateCaret

TWindow::ShowCaret


TWindow::HiliteMenuItem

See Also	TWindow

Syntax

bool HiliteMenuItem(HMENU hMenu, uint idItem, uint hilite);

Description

Either highlights or removes highlighting from a top-level item in the menu. idItem indicates the menu item to be processed. hilite (which contains a value that indicates if the idItem is to be highlighted or is to have the highlight removed) can be one or more of the following constants:

Value	Meaning

MF_BYCOMMAND	The idItem  parameter contains the menu item's identifier.

MF_BYPOSITION	The idItem  parameter contains the zero-based relative position of the menu item.

MF_HILITE	Highlights the menu item. If this value is not specified, highlighting is removed from the item.

MF_UNHILITE	Removes the menu item's highlighting.

If the menu is set to the specified condition, HiliteMenuItem returns true; otherwise, it returns false.


See Also

TWindow::GetMenu


TWindow::HoldFocusHwnd

TWindow

Syntax

virtual bool HoldFocusHWnd(HWND hWndLose, HWND hWndGain);

Description

Responds to a request by a child window to hold its HWND when it is losing focus. Stores the child's HWND in HoldFocusHwnd.


TWindow::IdleAction

TWindow

Syntax

virtual bool IdleAction(long idleCount);

Description

Called when no messages are waiting to be processed, IdleAction performs idle processing as long as true is returned. idleCount specifies the number of times idleAction has been called between messages.


TWindow::Invalidate

See Also	TWindow

Syntax

void Invalidate(bool erase = true);

Description

Invalidates (mark for painting) the entire client area of a window. The window then receives a message to redraw the window. By default, the background of the client area is marked for erasing.


See Also

TWindow::Validate

TWindow::InvalidateRect


TWindow::InvalidateRect

See Also	TWindow

Syntax

void InvalidateRect(const TRect&, bool erase = true);;

Description

Invalidates a specified client area. By default, the background of the client area to be invalidated is marked for erasing.


See Also

TWindow::ValidateRect

TWindow::Invalidate


TWindow::InvalidateRgn

See Also	TWindow

Syntax

void InvalidateRgn(HRGN hRgn, bool erase = true);

Description

Invalidates a client area within a region specified by the hRgn  parameter when the application receives a WM_PAINT message. The region to be invalidated is assumed to have client coordinates. If hRgn is 0, the entire client area is included in the region to be updated. The parameter erase specifies whether the background with the update region needs to be erased when the region to be updated is determined.  If erase is true, the background is erased; if erase  is false, the background is not erased when the Paint function is called. By default, the background within the region is marked for erasing.


See Also

TWindow::ValidateRgn


TWindow::IsChild

TWindow

Syntax

bool IsChild(HWND hWnd) const;

Description

 Returns true if the window is a child window or a descendant window of this window. A window is considered a child window if it is the direct descendant of a given parent window and the parent window is in a chain of windows leading from the original overlapped or pop-up window down to the child window. hWnd identifies the window to be tested.


TWindow::IsDlgButtonChecked

TWindow

Syntax

uint IsDlgButtonChecked(int buttonId) const;

Description

Indicates if the child button specified in the integer parameter, buttonId, is checked, or if a button is grayed, checked, or neither. If the return value is 0, the button is unchecked. If the return value is 1, the button is checked. If the return value is 3, the button state is undetermined. This function sends a BM_GETCHECK message to the specified button control.


TWindow::IsFlagSet

See Also	TWindow

Syntax

bool IsFlagSet(TWindowFlag mask);

Description

Returns the state of the bit flag in Attr.Flags whose mask is supplied. Returns true if the bit flag is set, and false if not set.


See Also

TWindowAttr struc


TWindow::IsIconic

TWindow

Syntax

bool IsIconic() const;

Description

Returns true if window is iconic or minimized.


TWindow::IsWindow

TWindow

Syntax

bool IsWindow() const;

Description

Returns true if an HWND is being used.


TWindow::IsWindowEnabled

TWindow

Syntax

bool IsWindowEnabled();

Description

Returns true if the window is enabled. Use the function EnableWindow to enable or disable a window.


TWindow::IsWindowVisible

TWindow

Syntax

bool IsWindowVisible() const;

Description

Returns true if the window is visible. By default, TWindow's constructor sets the window style attribute (WS_VISIBLE) so that the window is visible.


TWindow::IsZoomed

TWindow

Syntax

bool IsZoomed() const;

Description

Returns true if window is zoomed or maximized.


TWindow::KillTimer

See Also	TWindow

Syntax

bool KillTimer(uint timerId);

Description

Gets rid of the timer and removes any WM_TIMER messages from the message queue. timerId contains the ID number of the timer event to be killed.


See Also

TWindow::SetTimer


TWindow::LockWindowUpdate

TWindow

Syntax

bool LockWindowUpdate();

Description

Prevents or enables window drawing for one window at a time. If the window is locked, returns true; otherwise, returns false, which indicates either that an error occurred or that some other window is already locked.

If any drawing is attempted within a locked window or locked child windows, the extent of the attempted operation is saved within a bounding rectangle. When the window is then unlocked, the area within the rectangle is invalidated, causing a paint message to be sent to this window. If any drawing occurred while the window was locked for updates, the area is invalidated.


TWindow::MapWindowPoints

TWindow

Syntax

void MapWindowPoints(HWND hWndTo, TPoint* points, int count) const;

Description

Maps a set of points in one window to a relative set of points in another window. hWndTo specifies the window to which the points are converted. points points to the array containing the points. If hWndTo is 0, the points are converted to screen coordinates. count specifies the number of points structures in the array.


TWindow::MessageBox

See Also	TWindow

Syntax

int MessageBox(const char far* text,const char far* caption = 0, uint type = MB_OK);

Description

Creates and displays a message box that contains a message (text), a title (caption), and icons or push buttons (type). If caption is 0, the default title is displayed. Although type is set to one push button by default, it can contain a combination of the  MB_Xxxx message constants. This function returns one of the following constants:

Value	Description

IDABORT	User selected the abort button.

IDCANCEL	User selected the cancel button.

IDIGNORE	User selected the ignore button.

IDNO	User selected the no button.

IDOK	User selected the OK button

IDRETRY	User selected the retry button.

IDYES	User selected the yes button.

If BWCC is already enabled, the message box will be BWCC-enabled. If CTRL 3D is already enabled, the message box will be CTRL-3D-enabled. If neither BWCC nor CTRL 3D is enabled, the message box will be displayed as a standard windows message box.


See Also

TWindow::PostMessage

MB_Xxxx message constants


TWindow::MoveWindow

See Also	TWindow

Syntax 1

void MoveWindow(int x, int y, int w, int h, bool repaint = false);

Description

Repositions the specified window. x and y specify the new upper left coordinates of the window; w and h specify the new width and height, respectively. If repaint is false, the window is not repainted after it is moved.

Syntax 2

void MoveWindow(const TRect& rect, bool repaint = false);

Description

Repositions the window. rect references the left and top coordinates and the width and height of the new screen rectangle. If repaint is false, the window is not repainted after it is moved.


See Also

TWindow::RedrawWindow


TWindow::Next

See Also	TWindow

Syntax

TWindow* Next();

Description

Returns a pointer to the next sibling window in the window's sibling list.


See Also

TWindow::Previous


TWindow::NumChildren

TWindow

Syntax

unsigned NumChildren();

Description

Returns the number of child windows of the window.


TWindow::OpenClipboard

TWindow

Syntax

TClipboard& OpenClipboard();

Description

Opens the clipboard and prevents another application from changing the contents of the clipboard. This function fails if another window has already opened the clipboard.


TWindow::Operator HWND

TWindow

Syntax

operator HWND()const;

Description

Allows a TWindow& to be used as an HWND in Windows API calls by providing an implicit conversion from TWindow to HWND.


TWindow::Paint

TWindow

Syntax

virtual void Paint(TDC& dc, bool erase, TRect& rect);

Description

Repaints the client area (the area you can use for drawing) of a window. Called by base classes when responding to a WM_PAINT message, Paint serves as a placeholder for derived types that define Paint member functions. Paint is called by EvPaint and requested automatically by Windows to redisplay the window's contents. dc is the paint display context supplied to text and graphics output functions. The supplied reference to the rect structure is the bounding rectangle of the area that requires painting. erase indicates whether the background needs erasing.


TWindow::PostMessage

See Also	TWindow

Syntax

bool PostMessage(uint msg, WPARAM wParam = 0, LPARAM lParam=0) const;

Description

Posts a message (msg) to the window in the application's message queue. PostMessage returns without waiting for the corresponding window to process the message.


See Also

TWindow::ForwardMessage

TWindow::MessageBox


TWindow::PerformCreate

TWindow

Syntax

virtual void PerformCreate(int menuOrId);

Description

Called from Create to perform the final step in creating an MS-Windows interface element to be associated with an ObjectWindows window. PerformCreate can be overridden to provide alternate HWND implementation.


TWindow::PreProcessMsg

See Also	TWindow

Syntax

virtual bool PreProcessMsg(MSG& msg);

Description

Allows preprocessing of queued messages prior to dispatching. If you override this method in a derived class, be sure to call the base class's PreProcessMsg because it handles the translation of accelerator keys. When a nonzero value is returned, message processing stops.


See Also

TApplication::ProcessAppMsg


TWindow::Previous

See Also	TWindow

Syntax

TWindow* Previous();

Description

Returns a pointer to the previous window in the window's sibling list.


See Also

TWindow::Next


TWindow::ReceiveMessage

TWindow

Syntax

LRESULT ReceiveMessage(uint msg, WPARAM wParam = 0, LPARAM lParam = 0);

Description

Called from StdWndProc, ReceiveMessage is the first member function called when a message is received. It calls HandleMessage from within the try block of the exception-handling code. In this way, exceptions can be caught and suspended before control is returned to exception-unsafe Windows code.


TWindow::RedrawWindow

See Also	TWindow

Syntax

bool RedrawWindow(TRect* update, HRGN hUpdateRgn, uint redrawFlags = RDW_INVALIDATE | RDW_UPDATENOW | RDW_ERASE);

Description

Redraws the rectangle specified by update and the region specified by hUpdateRgn. redrawFlags can be a combination of one or more of the following RDW_Xxxx Redraw Window constants used to invalidate or validate a window:

Flags that invalidate a window

Value	Description

RDW_ERASE	When the window is repainted, it receives a WM_ERASEBKGND message. If RDW_INVALIDATE is not also specified, this flag has no effect.

RDW_FRAME	Any part of the non-client area of the window receives a WM_NCPAINT message if it intersects the region to be updated.

RDW_INTERNALPAINT	A WM_PAINT message is posted to the window whether or not it contains an invalid region.

RDW_INVALIDATE	Invalidates either hUpdateRgn or update. In cases where both are 0, the entire window becomes invalid.

Flags that validate a window

Value	Description

RDW_NOERASE	The window is prevented from receiving any WM_ERASEBKGND messages.

RDW_NOFRAME	The window is prevented from receiving any WM_NCPAINT messages. The flag RDW_VALIDATE must also be used with this flag.

RDW_NOINTERNALPAINT	The window is prevented from receiving internal WM_PAINT messages, but does not prevent the window from receiving WM_PAINT messages from invalid regions.

RDW_VALIDATE	Validates update and hUpdateRgn. However, if both are 0, the entire window area is validated. The flag does not have any effect on internal WM_PAINT messages.

Flags that control when the window is repainted

Value	Description

RDW_ERASENOW	Before the function returns, the specified windows will receive WM_NCPAINT and WM_ERASEBKGND messages.

RDW_UPDATENOW	Before the function returns, the specified windows will receive WM_NCPAINT, WM_ERASEBKGND, as well as WM_PAINT messages.


See Also

TWindow::GetUpdateRect


TWindow::Register

See Also	TWindow

Syntax

virtual bool Register();

Description

Registers the Windows registration class of this window, if this window is not already registered. Calls GetClassName and GetWindowClass to retrieve the Windows registration class name and attributes of this window. Register returns true if this window is registered.


See Also

TWindow::GetClassName

TWindow::GetWindowClass

WNDCLASS struct


TWindow::RegisterHotKey

See Also	TWindow

Syntax

bool RegisterHotKey(int idHotKey, uint modifiers, uint virtKey);

Description

Registers a hotkey ID with the current application. modifiers can be a combination of keys that must be pressed to activate the specified hotkey, such as HOTKEYF_SHIFT, HOTKEYF_CONTROL, and HOTKEYF_ALT.


See Also

TWindow::UnRegisterHotKey


TWindow::ReleaseCapture

TWindow

Syntax

static void ReleaseCapture();

Description

Releases the mouse capture from this window.


TWindow::RemoveProp

See Also	TWindow

Syntax 1

HANDLE RemoveProp(uint16 atom) const;

Description

Removes the property specified by atom from the application's property list. atom indicates the string to be removed. Returns the handle of the given string or NULL if no string exists in the window's property list.

Syntax 2

HANDLE RemoveProp(const char far* str) const;

Description

Removes the property specified by str, a null-terminated string, from the application's property list. Returns the handle of the given string or NULL if no string exists in the window's property list.


See Also

TWindow::GetProp


TWindow::RouteCommandEnable

See Also	TWindow

Syntax

void RouteCommandEnable(HWND hInitCmdTarget, TCommandEnabler& ce);

Description

 Walks the chain of windows from the initial target window to this window. If it finds a window to receive the message, RouteCommandEnable dispatches the command enabler to that window. hInitCmdTarget is the handle to the initial command target window, which can be focus window but does not need to be. ce is a reference to the command enabler.

Other classes use this function to perform particular command enabling tasks: For example, TFrameWindow calls RouteCommandEnable to perform the majority of its menu command enabling tasks. When it is an embedded window, TOleWindow also uses RouteCommandEnable to perform command enabling.


See Also

TFrameWindow::EvCommandEnable

TOleWindow::EvCommandEnable

TCommandEnabler class


TWindow::ScreenToClient

TWindow

Syntax

void ScreenToClient(TPoint& point) const;

Description

Uses the screen coordinates specified in point to calculate the client window's coordinates and then places the new coordinates into point.


TWindow::ScrollWindow

See Also	TWindow

Syntax

void ScrollWindow(int dx, int dy, const TRect* scroll = 0, const TRect far* clip = 0);

Description

Scrolls a window in the vertical (dx) and horizontal (dy) directions. scroll indicates the area to be scrolled. If 0, the entire client area is scrolled. clip specifies the clipping rectangle to be scrolled. Only the area within clip is scrolled. If clip is 0, the entire window is scrolled.


See Also

TWindow::ScrollWindowEx


TWindow::ScrollWindowEx

See Also	TWindow

Syntax

void ScrollWindowEx(int dx, int dy, const TRect far* scroll = 0, const TRect far* clip = 0, HRGN hUpdateRgn = 0, TRect far* update = 0, uint flags = 0);

Description

Scrolls a window in the vertical (dx) and horizontal (dy) directions. scroll indicates the area to be scrolled. If 0, the entire client area is scrolled. clip specifies the clipping rectangle to be scrolled. Only the area within clip is scrolled. If clip is 0, the entire window is scrolled. update indicates the region that will receive the boundaries of the area that becomes invalidated as a result of scrolling. flags, which determines how the window's children are scrolled, can be one of the following SW_Xxxx  Scroll Window constants:

Value	Description

SW_ERASE	Erases the invalidated region after sending an erase background message to the window indicated by the SW_INVALIDATE flag value.

SW_INVALIDATE	Invalidates the region indicated by the hUpdate parameter.

SW_SCROLLCHILDREN	Scrolls all the child window intersecting the rectangle pointed to by the scroll parameter.


See Also

TWindow::ScrollWindow

TWindow::Show


TWindow::SendDlgItemMessage

See Also	TWindow

Syntax

LRESULT SendDlgItemMessage(int childId, uint msg, WPARAM wParam = 0, LPARAM lParam = 0);

Description

Sends a message (msg) to the control specified in childId.


See Also

TWindow::SendMessage


TWindow::SendMessage

See Also	TWindow

Syntax

LRESULT SendMessage(uint msg, WPARAM wParam = 0, LPARAM lParam = 0);

Description

Sends a message (msg) to a specified window or windows. After it calls the window procedure, it waits until the window procedure has processed the message before returning.


See Also

TWindow::ChildBroadcastMessage

TWindow::HandleMessage

TWindow::SendDlgItemMessage


TWindow::SendNotification

TWindow

Syntax

void SendNotification(int id, int notifyCode, HWND hCtl, uint msg = WM_COMMAND);

Description

Repacks a command message (msg) so that a child window (hCtl) can send a message to its parent regardless of whether this is a WIN16 or WIN32 application.


TWindow::SetActiveWindow

See Also	TWindow

Syntax

HWND SetActiveWindow();

Description

Activates a top-level window. Returns a handle to the previously active window.


See Also

TWindow::GetActiveWindow


TWindow::SetBkgndColor

See Also	TWindow

Syntax

void SetBkgndColor(uint32 color);

Description

Sets the background color for the window. You can also get the current color of an element displayed on the screen. For example,

layout -> SetBkgndColor(GetSysColor(COLOR_APPWORKSPACE));

Uses one of the Windows COLOR values (in this case, the color of multiple document interface (MDI) applications).


See Also

TWindow::BkgndColor


TWindow::SetCaption

See Also	TWindow

Syntax

void SetCaption(const char far* title);

Description

Copies title to an allocated string pointed to by title. Sets the caption of the interface element to title. Deletes any previous title.


See Also

TWindow::GetWindowTextTitle

TWindow::Title


TWindow::SetCapture

TWindow

Syntax

HWND SetCapture();

Description

Sets the mouse capture to the current window. All mouse input is directed to this window.


TWindow::SetCaretBlinkTime

See Also	TWindow

Syntax

static void SetCaretBlinkTime(uint16 milliSecs);

Description

Sets the caret blink rate in milliseconds.


See Also

TWindow::GetCaretBlinkTime


TWindow::SetCaretPos

See Also	TWindow

Syntax 1

static void SetCaretPos(int x, int y);

Description

Sets the position of the caret in the coordinates of the client window. x and y indicate the client coordinates of the caret.

Syntax 2

static void SetCaretPos(const TPoint& pos);

Description

Sets the position of the caret in the coordinates of the client window. pos indicates the client coordinates of the caret.


See Also

TWindow::GetCaretPos

TWindow::ShowCaret


TWindow::SetClassLong

See Also	TWindow

Syntax

long SetClassLong(int index) const;

Description

Sets the long value at the specified offset (index). Depending on the value of index, SetClassLong sets a handle to a background brush, cursor, icon, module, menu, window function, or extra class bytes.


See Also

TWindow::GetClassLong


TWindow::SetClassWord

See Also	TWindow

Syntax

uint16 SetClassWord(int index, uint16 newWord);

Description

Sets the word value at the specified offset (index). Depending on the value of index, SetClassLong sets the number of bytes of class information, of additional window information, or the style bits. Unlike SetClassLong, SetClassWord uses one of the following GCW_xxxx Class Word constants:

Value	Meaning

GCW_HBRBACKGROUND	Sets a handle for a background brush.

GCW_HCURSOR	Sets a handle of a cursor.

GCW_HICON	Sets a handle of an icon.

GCW_STYLE	Sets a style bit for a window class.


See Also

TWindow::GetClassWord


TWindow::SetCursor

See Also	TWindow

Syntax

bool SetCursor(TModule* module, TResId resId);

Description

Sets the cursor position for the window using the given module and ResId. If the  module  parameter is 0, CursorResId can be one of the  IDC_xxxx constants that represent different kinds of cursors. See the data member for a list of these cursor values. If the mouse is over the client area, SetCursor changes the cursor that is displayed.


See Also

TWindow::GetCursorPos

TWindow::CursorResId


TWindow::SetDlgItemInt

See Also	TWindow

Syntax

void SetDlgItemInt(int childId, uint value, bool isSigned = true) const;

Description

Sets the child window with the Id (childId) in the window to the integer value specified in value. If isSigned is true, the value is signed.


See Also

TWindow::GetDlgItem


TWindow::SetDlgItemText

See Also	TWindow

Syntax

void SetDlgItemText(int childId, const char far* text) const;

Description

Sets the title or text of a control in a dialog box. childId identifes the control. text points to the text buffer containing the text that is to be copied into the control.


See Also

TWindow::GetDlgItemText


TWindow::SetDocTitle

TWindow

Syntax

virtual bool SetDocTitle(const char far* docname, int index);

Description

Stores the title of the document (docname). index is the number of the view displayed in the document's caption bar. In order to determine what the view number should be, SetDocTitle makes two passes: the first pass checks to see if there's more than one view, and the second pass, if there is more than one view, assigns the next number to the view. If there is only one view, index is 0; therefore, the document does not display a view number. When TDocument is checking to see if more than one view exists, index is -1. In such cases, only the document's title is displayed in the caption bar.

SetDocTitle returns true if there is more than one view and TDocument displays the number of the view passed in index.


TWindow::SetFlag

See Also	TWindow

Syntax

void SetFlag(TWindowFlag mask);

Description

If true is supplied, the bits in Attr.Flags in Mask are set. Otherwise, the bit is cleared. Mask can be any one, or a combination, of the wfXxxx constants.


See Also

TWindow::IsFlagSet

TWindow: Flag enum


TWindow::SetFocus

See Also	TWindow

Syntax

HWND SetFocus();

Description

Sets the keyboard focus to current window and activates the window that receives the focus by sending a WM_SETFOCUS message to the window. All future keyboard input is directed to this window, and any previous window that had the input focus loses it. If successful, SetFocus returns a handle to the window that has the focus; otherwise, it returns NULL.


See Also

TWindow::GetFocus


TWindow::SetModule

See Also	TWindow

Syntax

void SetModule(TModule* module);

Description

Sets the default module for this window.


See Also

TWindow::GetModule


TWindow::SetMenu

See Also	TWindow

Syntax

bool SetMenu(HMENU hMenu);

Description

Sets the specified window's menu to the menu indicated by hMenu. If hMenu is 0, the window's current menu is removed. SetMenu returns 0 if the menu remains unchanged; otherwise, it returns a nonzero value.


See Also

TWindow::GetMenu

TMDIFrame::SetMenu


TWindow::SetNext

TWindow

Syntax

void SetNext(TWindow* next);

Description

Sets the next window in the sibling list.


TWindow::SetParent

See Also	TWindow

Syntax

virtual void SetParent(TWindow* newParent);

Description

Sets the parent for the specified window by setting Parent to the specified new Parent window object. Removes this window from the child list of the previous parent window, if any, and adds this window to the new parent's child list.


See Also

TWindow::GetParent


TWindow::SetProp

See Also	TWindow

Syntax 1

bool SetProp(uint16 atom, HANDLE data) const;

Description

Adds an item to the property list of the specified window. atom contains a value that identifies the data entry to be added to the property list.

Syntax 2

bool SetProp(const char far* str, HANDLE data) const;

Description

Adds an item to the property list of the specified window. str points to the string used to identify the entry data to be added to the property list.


See Also

TWindow::GetProp


TWindow::SetRedraw

TWindow

Syntax

void SetRedraw(bool redraw);

Description

Sends a WM_SETREDRAW message to a window so that changes can be redrawn (redraw = true) or to prevent changes from being redrawn (redraw = false).


TWindow::SetScrollPos

See Also	TWindow

Syntax

int SetScrollPos(int bar, int pos, bool redraw = true);

Description

Sets the thumb position in the scroll bar. bar identifies the position (horizontal, vertical, or scroll bar control) to return and can be one of the SB_Xxxx scroll bar constants.


See Also

TWindow::GetScrollPos


TWindow::SetScrollRange

See Also	TWindow

Syntax

void SetScrollRange(int bar, int minPos, int maxPos, bool redraw = true);

Description

Sets the thumb position in the scroll bar. bar identifies the position (horizontal, vertical, or scroll bar control) to set and can be one of the SB_Xxxx scroll bar constants. minPos and maxPos specify the lower and upper range, respectively, of the scroll bar positions.


See Also

TWindow::GetScrollRange

TWindow::SetScrollRange


TWindow::SetSysModalWindow

See Also	TWindow

Syntax

HWND SetSysModalWindow();

Description

Makes the indicated window a system-modal window.


See Also

TWindow::GetSysModalWindow


TWindow::SetTimer

See Also	TWindow

Syntax

uint SetTimer(uint timerId, uint timeout, TIMERPROC proc = 0);

Description

Creates a timer object associated with this window. timerID contains the ID number of the timer to be created, timeout specifies the length of time in milliseconds, and proc identifies the address of the function that's to be notified when the timed event occurs. If proc is 0, WM_TIMER messages are placed in the queue of the application that called SetTimer for this window.


See Also

TWindow::KillTimer


TWindow::SetTransferBuffer

See Also	TWindow

Syntax

void SetTransferBuffer(void* transferBuffer);

Description

Sets TransferBuffer to transferBuffer.


See Also

TWindow::Transfer

TWindow::TransferData


TWindow::SetWindowFont

TWindow

Syntax

void SetWindowFont(HFONT font, bool redraw);

Description

Sets the font that a control uses to draw text. font, which specifies the font being used, is NULL if the default system font is used. If redraw is true, the control redraws itself after the font is set; if false, the control does not redraw itself. See the sample program, FILEBROW.CPP, for an example of how to set the font for a file browser list box.


TWindow::SetWindowLong

See Also	TWindow

Syntax

long SetWindowLong(int index, long newLong);

Description

Changes information about the window. Depending on the value of index, SetWindowLong sets a handle to a background brush, cursor, icon, module, menu, or window function. The window style can be one of the GWL_xxxx values that represent styles.


See Also

TWindow::SetWindowWord


TWindow::SetWindowPlacement

See Also	TWindow

Syntax

bool SetWindowPlacement(const WINDOWPLACEMENT* place);

Description

Sets the window to a display mode and screen position. place points to a window placement structure that specifies whether the window is to be hidden, minimized or displayed as an icon, maximized, restored to a previous position, activated in its current form, or activated and displayed in its normal position.


See Also

TWindow::GetWindowPlacement

TWindow::Show


TWindow::SetWindowPos

See Also	TWindow

Syntax 1

void SetWindowPos(HWND hWndInsertAfter, const TRect& rect, uint flags);

Description

Changes the size of the window pointed to by rect. flags contains one of the SWP_Xxxx Set Window Position constants (described below) that specify the size and position of the window. If flags is set to SWP_NOZORDER, SetWindowPos ignores the hWndInsertAfter parameter and retains the current ordering of the child, pop-up, or top-level windows.

Syntax 2

void SetWindowPos(HWND hWndInsertAfter, int x, int y, int w, int h, uint flags);

Description

Changes the size of the window pointed to by x, y, w, and h. flags contains one of the SWP_Xxxx  Set Window Position constants that specify the size and position of the window. If flags is set to SWP_NOZORDER, SetWindowPos ignores the hWndInsertAfter parameter and retains the current ordering of the child, pop-up, or top-level windows.

SWP_Xxxx Set Window Position Constants

Value	Description

SWP_DRAWFRAME	Draws a frame around the window.

SWP_FRAMECHANGED	Sends a message to the window to recalculate the window's size. If this flag is not set, a recalculate size message is sent only at the time the window's size is being changed.

SWP_HIDEWINDOW	Hides the window.

SWP_NOACTIVATE	Does not activate the window. If this flag is not set, the window is activated and moved to the top of the stack of windows.

SWP_NOCOPYBITS	Discards the entire content area of the client area of the window. If this flag is not set, the valid contents are saved and copied into the window after the window is resized or positioned.

SWP_NOMOVE	Remembers the window's current position.

SWP_NOSIZE	Remembers the window's current size.

SWP_NOREDRAW	Does not redraw any changes to the window. If this flag is set, no repainting of any window area (including client, nonclient, and any window part uncovered as a result of a move) occurs. When this flag is set, the application must explicitly indicate if any area of the window is invalid and needs to be redrawn.

SWP_NOZORDER	Remembers the current Z-order (window stacking order).

SWP_SHOWWINDOW	Displays the window.


See Also

TWindow::GetWindowPlacement


TWindow::SetWindowText

See Also	TWindow

Syntax

void SetWindowText(const char far* str);

Description

Sets the window title to a buffer pointed to by str. maxCount indicates the number of characters to copy into the buffer. Note that this does not update this window's Title member. Use SetCaption if the window's Title member needs to be synchronized with the window's title.


See Also

TWindow::GetWindowText


TWindow::SetWindowWord

See Also	TWindow

Syntax

uint16 SetWindowWord(int index, uint16 newWord);

Description

Changes information about the window. index specifies a byte offset of the word to be changed to the new value (newWord).


See Also

TWindow::GetWindowWord

TWindow::SetWindowLong


TWindow::Show

TWindow

Syntax

void Show(int cmdShow);

Description

After ensuring that the TWindow interface element has a valid handle, Show displays the TWindow on the screen in a manner specified by cmdShow, which can be one of the following SW_Xxxx Show Window constants:

Value	Description

SW_SHOWDEFAULT	Show the window in its default configuration. Should be used at startup.

SW_HIDE	Hide the window and activate another window.

SW_MINIMIZE	Minimize the window and activate the top-level window in the list.

SW_RESTORE	Same as SW_SHOWNORMAL.

SW_SHOW	Show the window in the window's current size and position.

SW_SHOWMAXIMIZED	Activate and maximize the window.

SW_SHOWMINIMIZED	Activate window as an icon.

SW_SHOWNA	Display the window as it is currently.

SW_SHOWMINNOACTIVE	Display the window as an icon.

SW_SHOWNORMAL	Activate and display the window in its original size and position.

SW_SHOWSMOOTH	Show the window after updating it in a bitmap.


TWindow::ShowCaret

See Also	TWindow

Syntax

void ShowCaret();

Description

Displays the caret in the specified shape in the active window at the current position.


See Also

TWindow::CreateCaret

TWindow::HideCaret


TWindow::ShowOwnedPopups

See Also	TWindow

Syntax

void ShowOwnedPopups(bool show);

Description

Shows or hides all owned popup windows according to the value of show.


See Also

TWindow::Show


TWindow::ShowScrollBar

See Also	TWindow

Syntax

void ShowScrollBar(int bar, bool show = true);

Description

Displays or hides the scroll bar. bar specifies whether the bar is a control itself or part of the window's nonclient area. If bar is part of the nonclient area, it can be one of the SB_Xxxx scroll bar constants (specifically, SB_BOTH, SB_HORZ, or SB_VERT). If it is a control, it should be SB_CTRL. If show is true, the scroll bar is displayed; if false, it is hidden.


See Also

TWindow::GetScrollRange


TWindow::ShowWindow

TWindow

Syntax

virtual bool ShowWindow(int cmdShow);

Description

Displays the window according to the value of cmdShow. Show describes the SW_xxxx constants passed in cmdShow and is the preferred method of showing the window.


TWindow::ShutDownWindow

TWindow

Syntax 1

void ShutDownWindow(int retVal = 0);

Description

This inline version of ShutDownWindow calls the static version of ShutDownWindow.

Syntax 2

static void ShutDownWindow(TWindow* win, int retVal = 0);

Description

This version of ShutDownWindow unconditionally shuts down a given window, calls Destroy on the interface element, and then deletes the interface object. Instead of using ShutDownWindow, you can call Destroy directly and then delete the interface object.


TWindow::SubclassWindowFunction

See Also	TWindow

Syntax

void SubclassWindowFunction();

Description

Installs the instance thunk as the WindowProc and saves the old window function in DefaultProc.


See Also

TWindow::DefaultProcessing


TWindow::Transfer

See Also	TWindow

Syntax

virtual uint Transfer(void* buffer, TTransferDirection direction);

Description

Transfers data to or from any window with or without children and returns the total size of the data transferred. Transfer is a general mechanism for data transfer that can be used with or without using TransferData. The direction supplied specifies whether data is to be read from or written to the supplied buffer, or whether the size of the transfer data is simply to be returned. Data is not transferred to or from any child windows whose wfTransfer flag is not set. The return value is the size (in bytes) of the transfer data.


See Also

TWindow::TransferData


TWindow::TransferData

See Also	TWindow

Syntax

virtual void TransferData(TTransferDirection direction);

Description

A window usually calls TransferData during setup and closing of windows and relies on the constructor to set TransferBuffer to something meaningful. TransferData calls the Transfer member function of each participating child window, passing a pointer to TransferBuffer as well as the direction specified in direction (tdSetData, tdGetData, or tdSizeData).


See Also

TWindow::EnableTransfer

TWindow::DisableTransfer

TWindow::SetupWindow


TWindow::UnregisterHotKey

See Also	TWindow

Syntax

bool UnregisterHotKey(int idHotKey);

Description

Unregisters a hotkey ID with the current application.


See Also

TWindow::RegisterHotKey


TWindow::UpdateWindow

TWindow

Syntax

void UpdateWindow();

Description

Updates the client area of the specified window by immediately sending a WM_PAINT message.


TWindow::Validate

See Also	TWindow

Syntax

void Validate();

Description

Calls the function ValidateRect to validate (that is, remove from the area to be updated) the entire client area (the area you can use for drawing).


See Also

TWindow::InValidate


TWindow::ValidateRect

See Also	TWindow

Syntax

void ValidateRect(const TRect& rect);

Description

Validates a portion of the client area indicated by rect.


See Also

TWindow::InvalidateRect


TWindow::ValidateRgn

See Also	TWindow

Syntax

void ValidateRgn(HRGN hRgn);

Description

Validates the client area within a region of the current window. hRgn is a handle to the client area that is to be removed from the region to be updated. If hRgn is NULL, the entire client area is removed from the region to be updated.


See Also

TWindow::InvalidateRgn


TWindow::WindowFromPoint

See Also	TWindow

Syntax

static HWND WindowFromPoint(const TPoint& point) const;

Description

Returns the handle of the window in which the specified point (point) lies.


See Also

TWindow::ChildWindowFromPoint


TWindow::WindowProc

See Also	TWindow

Syntax

virtual LRESULT WindowProc(uint msg, WPARAM wParam, LPARAM lParam);

Description

Processes incoming messages by calling EvCommand to handle WM_COMMAND messages, EvCommandEnable to handle WM_COMMAND_ENABLE messages, and dispatching for all other messages.


See Also

TWindow::DefWindowProc


TWindow::WinHelp

TWindow

Syntax

bool WinHelp(const char far* helpFile, uint command, uint32 data);

Description

Invokes a specified help system. helpFile points to a string containing the directory path and name of the help file. command, which indicates the type of help requested, can be one of the Windows Help_xxxx constants such as HELP_CONTEXT, HELP_HELPONHELP, HELP_INDEX, HELP_MULTIKEY, HELP_QUIT, or HELP_SETINDEX. data contains keywords that indicate the help topic items.

For example, in the sample ObjectWindows file, HELP.CPP, WinHelp is called with the arguments HELP_CONTEXT and HELP_MENUITEMA if the F1 key is pressed.

void TOwlHelpWnd::CmMenuItemA()

{

   if (F1Pressed) {

     WinHelp(HelpFile, HELP_CONTEXT, HELP_MENUITEMA);

     F1Pressed = false;

} else {

     MessageBox("In Menu Item A command", Title, MB_ICONINFORMATION);

 }

}

You can also include bitmaps in your Help file by referencing their file names or by copying them from the Clipboard. For more information about how to create Help files, see the online Help documentation.


TWindow::BkgndColor

TWindow

Syntax

uint32 BkgndColor;

Description

Stores the current background color set by TWindow::SetBkgndColor.


TWindow::CursorModule

See Also	TWindow

Syntax

TModule* CursorModule;

Description

Holds the module ID for the specified cursor. A value of 0 indicates a standard system cursor.


See Also

TWindow::CursorResId


TWindow::CursorResId

See Also	TWindow

Syntax

TResId CursorResId;

Description

Holds the cursor resource ID for the window's cursor. If the data member CursorModule is 0, CursorResId can be one of the following IDC_Xxxx constants that represent different kinds of cursors:

Value	Meaning

IDC_ARROW	Customary arrow cursor

IDC_CROSS	Crosshair cursor

IDC_IBEAM	I-beam cursor

IDC_ICON	Unfilled icon cursor

IDC_SIZE	A smaller square in the right inside corner of a larger square

IDC_SIZENESW	Dual-pointing cursor with arrows pointing southwest and northeast

IDC_SIZENS	Dual-pointing cursor with arrows pointing south and north

IDC_SIZENWSE	Dual-pointing cursor with arrows pointing southeast and northwest

IDC_SIZEWE	Dual-pointing cursor with arrows pointing east and west

IDC_UPARROW	Vertical arrow cursor

IDC_WAIT	Hourglass cursor


See Also

TWindow::SetCursor


TWindow::hAccel

TWindow

Syntax

HACCEL hAccel;

Description

Holds the handle to the current Windows accelerator table associated with this window.


TWindow::HCursor

TWindow

Syntax

HCURSOR HCursor;

Description

Holds a handle to the window's cursor. The cursor is retrieved using CursorModule and CursorResId and set using SetCursor.


TWindow::TransferBuffer

See Also	TWindow

Syntax

void* TransferBuffer;

Description

Points to a buffer to be used in transferring data in and out of the TWindow object. A TWindow object assumes that the buffer contains data used by the windows in its child list. If TransferBuffer is 0, no data is to be transferred.


See Also

tdxxxx constants


TWindow::CleanupWindow (protected)
TWindow::CleanupWindow

See Also	TWindow

Syntax

virtual void CleanupWindow();

Description

Always called immediately before the HWindow becomes invalid, CleanupWindow gives derived classes an opportunity to clean up HWND related resources. This function is the complement to SetupWindow.

Override this function in your derived class to handle window cleanup. Derived classes should call the base class's version of CleanupWindow as the last step before returning. The following example from the sample program, APPWIN.CPP, illustrates this process:

//Tell windows that we are not accepting drag and drop transactions any more and perform other window cleanup.

void

TAppWindow::CleanupWindow()

{

  AppLauncherCleanup();

  DragAcceptFiles(false);

  TWindow::CleanupWindow();

}


See Also

TWindow::SetupWindow


TWindow::DispatchScroll

TWindow

Syntax

void DispatchScroll(uint scrollCode, uint thumbPos, HWND hWndCtrl);

Description

Called by EvHScroll and EvVScroll to dispatch messages from scroll bars.


TWindow::GetClassName

See Also	TWindow

Syntax

virtual char far* GetClassName();

Description

Returns the Windows registration class name. The default class name is generated using the module name plus Window.  If you are registering a new class or changing the name of an existing window class, override this function in your derived class.


See Also

TWindow::GetWindowClass

WNDCLASS struct


TWindow::GetWindowClass

See Also	TWindow

Syntax

virtual void GetWindowClass(WNDCLASS& wndClass);

Description

Redefined by derived classes, GetWindowClass fills the supplied MS-Windows registration class structure with registration attributes, thus, allowing instances of TWindow to be registered. This function, along with GetClassName, allows Windows classes to be used for the specified ObjectWindows class and its derivatives. It sets the fields of the passed WNDCLASS parameter to the default attributes appropriate for a TWindow. The fields and their default attributes for the class are the following:

Value	Meaning

cbClsExtra	0 (the number of extra bytes to reserve after the Window class structure). This value is not used by ObjectWindows.

cbWndExtra	0 (the number of extra bytes to reserve after the Window instance). This value is not used by ObjectWindows.

hInstance	The instance of the class in which the window procedure exists

hIcon	0 (Provides a handle to the class resource.) By default, the application must create an icon if the application's window is minimized.

hCursor	IDC_ARROW (provides a handle to a cursor resource)

hbrBackground	COLOR_WINDOW + 1 (the system background color)

lpszMenuName	0 (Points to a string that contains the name of the class's menu.) By default, the windows in this class have no assigned menus.

lpszClassName	Points to a string that contains the name of the window class.

lpfnWndProc	The address of the window procedure. This value is not used by ObjectWindows.

style	CS_DBLCLKS

The style field can contain one or more of the following values:

CS_BYTEALIGNCLIENT	Aligns the window's client on a byte boundary in the x direction. This alignment, designed to improve performance, determines the width and horizontal position of the window.

CS_BYTEALIGNWINDOW	Aligns a window on a byte boundary in the x direction. This alignment, designed to improve performance, determines the width and horizontal position of the window.

CS_CLASSDC	Allocates a single device context (DC) that's going to be shared by all of the window in the class. This style controls how multi-threaded applications that have windows belonging to the same class share the same DC.

CS_DBLCLKS	Sends a double-click mouse message to the window procedure when the mouse is double-clicked on a window belonging to this class.

CS_GLOBALCLASS	Allows an application to create a window class regardless of the instance parameter. You can also create a global class by writing a DLL that contains the window class.

CS_HREDRAW	If the size of the window changes as a result of some movement or resizing, redraws the entire window.

CS_NOCLOSE	Disables the Close option on this window's system menu.

CS_OWNDC	Enables each window in the class to have a different DC.

CS_PARENTDC	Passes the parent window's DC to the child windows.

CS_SAVEBITS	Saves the section of the screen as a bitmap if the screen is covered by another window. This bitmap is later used to recreate the window when it is no longer obscured by another window.

CS_VREDRAW	If the height of the client area is changed, redraws the entire window.

After the Windows class structure has been filled with default values by the base class, you can override this function to change the values of the Windows class structure. For example, you might want to change the window's colors or the cursor displayed.


See Also

TWindow::GetClassName

WNDCLASS struct


TWindow::Init

TWindow

Syntax

void Init(TWindow* parent, const char far* title, TModule* module);

Description

Allows for further initialization after default construction of a window in virtually derived classes.


TWindow::LoadAcceleratorTable

TWindow

Syntax

void LoadAcceleratorTable();

Description

Loads a handle to the window's accelerator table specified in the TWindowAttr structure (Attr.AccelTable). If the accelerator does not exist, LoadAcceleratorTable produces an "Unable to load accelerator table" diagnostic message.


TWindow::RemoveChild

See Also	TWindow

Syntax

void RemoveChild(TWindow* child);

Description

Removes a child window. Uses the ObjectWindows list of objects rather the Window's HWND list.


See Also

TWindow::GetFirstChild

TWindow::GetLastChild

TWindow::Next

TWindow::Previous


TWindow::SetupWindow

See Also	TWindow

Syntax

virtual void SetupWindow();

Description

The first virtual function called when the HWindow becomes valid. TWindow's implementation performs window setup by iterating through the child list, attempting to create an associated interface element for each child window object for which autocreation is enabled. (By default, autocreation is enabled for windows and controls, and disabled for dialog boxes.) SetupWindow then calls TransferData. If a child window cannot be created, SetupWindow calls TXWindow with an IDS_CHILDCREATEFAIL message.

SetupWindow can be redefined in derived classes to perform additional special initialization. Note that the HWindow is valid when the overridden SetupWindow is called, and that the children's HWindows are valid after calling the base classes' SetupWindow function.

The following example from the sample program, APPWIN.CPP, illustrates the use of an overridden SetupWindow to setup a window, initialize .INI entries, and tell Windows that we want to accept drag and drop transactions:

void TAppWindow::SetupWindow()

{

  TFloatingFrame::SetupWindow();

  InitEntries();   // Initialize .INI entries.

  RestoreFromINIFile(); // from APPLAUNC.INI in the startup directory

  UpdateAppButtons();

  DragAcceptFiles(true);

}


See Also

TFrameWindow::SetupWindow

TComboBox::SetupWindow

TWindow::CleanupWindow


TWindow Response Table Entries

TWindow

There are two tables. The first one shows the standard response table entries. The second shows the Win32 response table entries.

Standard Response Table Entries

Response table entry	Member function

EV_WM_CREATE	EvCreate

EV_WM_CLOSE	EvClose

EV_WM_DESTROY	EvDestroy

EV_WM_SIZE	EvSize

EV_WM_MOVE	EvMove

EV_WM_NCDESTROY	EvNcDestroy

EV_WM_QUERYENDSESSION	EvQueryEndSession

EV_WM_COMPAREITEM	EvCompareItem

EV_WM_DELETEITEM	EvDeleteItem

EV_WM_DRAWITEM	EvDrawItem

EV_WM_MEASUREITEM	EvMeasureItem

EV_WM_CHILDINVALID	EvChildInvalid

EV_WM_VSCROLL	EvVScroll

EV_WM_HSCROLL	EvHScroll

EV_WM_PAINT	EvPaint

EV_WM_SETCURSOR	EvSetCursor

EV_WM_LBUTTONDOWN	EvLButtonDown

EV_COMMAND(CM_EXIT, CmExit)	CmExit

EV_WM_SYSCOLORCHANGE	EvSysColorChange

EV_WM_KILLFOCUS	EvKillFocus

EV_WM_ERASEBKGND	EvEraseBkgnd

Win32 Response Table Entries

Response table entry	Member function

EV_MESSAGE(WM_CTLCOLORMSGBOX, EvWin32CtlColor)	EvWin32CtlColor

EV_MESSAGE(WM_CTLCOLOREDIT, EvWin32CtlColor)	EvWin32CtlColor

EV_MESSAGE(WM_CTLCOLORLISTBOX, EvWin32CtlColor)	EvWin32CtlColor

EV_MESSAGE(WM_CTLCOLORBTN, EvWin32CtlColor)	EvWin32CtlColor

EV_MESSAGE(WM_CTLCOLORDLG, EvWin32CtlColor)	EvWin32CtlColor

EV_MESSAGE(WM_CTLCOLORSCROLLBAR, EvWin32CtlColor)	EvWin32CtlColor

EV_MESSAGE(WM_CTLCOLORSTATIC, EvWin32CtlColor)	EvWin32CtlColor


TWindowDC Class

OWL Hierarchy	Inheritance

Header File

dc.h

Description

Derived from TDC, TWindowDC is a device context (DC) class that provides access to the entire area owned by a window. TWindowDC is the base class for any DC class that releases its handle when it is finished.

Public Constructor and Destructor

TWindowDC(HWND wnd);

~TWindowDC();

Protected Constructor

TWindowDC();

Protected Data Member

HWND Wnd;


TWindowDC Public Constructor and Destructor

TWindowDC

Constructor

TWindowDC(HWND wnd);

Description

Creates a TWindow object with the given owned window. The data member Wnd is set to wnd.

Destructor

~TWindowDC();

Description

Destroys this object.


TWindowDC Protected Constructors
TWindowDC Protected Constructor

TWindowDC

Syntax

TWindowDC();

Description

Used for derived classes only.


TWindowDC::Wnd

See Also	TWindowDC

Syntax

HWND Wnd;

Description

Holds a handle to the window owned by this device context.


See Also

TWindowDC::TWindowDC


TWindowView Class

OWL Hierarchy	Inheritance

Header File

docview.h

Description

Derived from both TWindow and TView, TWindowView is a streamable base class that can be used for deriving window-based views. TWindowView's functions override TView's virtual function to provide their own implementation. By deriving a window-view class from TWindow and TView, you add window functionality to the view of your document.

Public Constructor and Destructor

TWindowView (TDocument& doc, TWindow* parent = 0);

~TWindowView();

Public Member Functions

bool CanClose();

const char far* GetViewName();

TWindow* GetWindow()

bool SetDocTitle(const char far* docname, int index)

static const char far* StaticName();

Response Table Entries

EV_ macros and member functions


TWindowView Public Constructor and Destructor

TWindowView

Constructor

TWindowView (TDocument& doc, TWindow* parent = 0);

Description

Constructs a TWindowView interface object associated with the window view. Sets ViewId to NextViewId. Calls the associated document's AttachView function (a private TDocument function) to attach the view to the document.

Destructor

~TWindowView();

Description

Destroys a TWindowView object and calls the associated document's DetachView function (a private TDocument function) to detach the view from the associated document.


TWindowView::CanClose

See Also	TWindowView

Syntax

bool CanClose();

Description

Overrides TWindow::CanClose and returns a nonzero value if the window can be closed. CanClose checks all the associated document's CanClose functions. These must return nonzero values before the window view can be closed.


See Also

TWindow::CanClose


TWindowView::GetViewName

TWindowView

Syntax

const char far* GetViewName();

Description

Overrides TView::GetViewName and returns StaticName, the name of the view.


TWindowView::GetWindow

See Also	TWindowView

Syntax

TWindow* GetWindow()

Description

Overrides TView::GetWindow and returns the TWindowView object as a TWindow.


See Also

TEditView::GetWindow


TWindowView::SetDocTitle

See Also	TWindowView

Syntax

bool SetDocTitle(const char far* docname, int index)

Description

Overrides TView::SetDocTitle and stores the document title. This name is forwarded up the parent chain until a TFrameWindow object accepts the data and displays it in its caption.


See Also

TView::SetDocTitle

TWindow::SetDocTitle


TWindowView::StaticName

TWindowView

Syntax

static const char far* StaticName();

Description

Returns "Window View," the descriptive name of the view. This title is displayed in the user-interface box.


TWindowView Response Table Entries

TWindowView

Response table entry	Member function

EV_VN_ISWINDOW	VnIsWindow


TWindow::TXWindow Class

TWindow	OWL Hierarchy	Inheritance

Header File

window.h

Description

A nested class, TXWindow describes an exception that results from trying to create an invalid window.

Public Constructors

TXWindow(TWindow* win = 0, uint resourceId = IDS_INVALIDWINDOW);

TXWindow(const TXWindow& src);

Public Data Members

TWindow* Window;

Public Member Functions

TXOwl* Clone();

static string Msg(TWindow*, uint resourceid);

void Throw();

int Unhandled(TModule* app, unsigned promptResId);


TWindow::TXWindow Public Constructors

TWindow::TXWindow

Syntax 1

TXWindow(TWindow* win = 0, uint resourceId = IDS_INVALIDWINDOW);

Description

Constructs a TXWindow object with a default resource ID of IDS_INVALIDWINDOW.

Syntax 2

TXWindow(const TXWindow& src);

Description

Constructs a TXWindow object with the window that failed.


TWindow::TXWindow::Window

TWindow::TXWindow

Syntax

TWindow* Window;

Description

Points to the window object that is associated with the exception.


TWindow::TXWindow::Clone

TWindow::TXWindow

Syntax

TXOwl* Clone();

Description

Makes a copy of the exception object. Clone() must be implemented in any class derived from TXOwl.


TWindow::TXWindow::Msg

TWindow::TXWindow

Syntax

static string Msg(TWindow*, uint resourceid);

Description

Converts the resource ID to a string and returns the string message.


TWindow::TXWindow::Throw

TWindow::TXWindow

Syntax

void Throw();

Description

Throws the exception object. Throw() must be implemented in any class derived from TXOwl.


TWindow::TXWindow::Unhandled

TWindow::TXWindow

Syntax

int Unhandled(TModule* app, unsigned promptResId);

Description

Called if an exception caught in the window's message loop has not been handled. Unhandled() deletes the window. This type of exception can occur if a window cannot be created.


TXBase class

See Also	OWL Hierarchy	Inheritance

Header File

except.h

Description

Derived from xmsg, TXBase is the base class for ObjectWindows and ObjectComponents exception-handling classes. The ObjectWindows classes that handle specific kinds of exceptions, such as out-of-memory or invalid window exceptions, are derived from TXOwl, which is in turn derived from TXBase. The ObjectComponents classes TXOle and TXAuto are derived directly from TXBase.

TXBase contains the functions Clone and Throw, which are overridden in all derived classes, as well as two constructors. The constructors increment InstanceCount, and the destructor decrements InstanceCount.

Public Constructors and Destructor

TXBase(const string& msg);

TXBase(const TXBase& src);

virtual ~TXBase();

Public Data Members

static int InstanceCount;

Public Member Functions

virtual TXBase* Clone();

virtual void Throw();


See Also

Working with TXBase


TXBase::InstanceCount

TXBase

Syntax

static int InstanceCount;

Description

Counts the number of TXBase and TXBase-derived objects existing in a single application.


TXBase Public Constructors and Destructor

See Also	TXBase

Syntax 1

TXBase(const string& msg);

Description

Calls the xmsg class's constructor that takes a string parameter and initializes xmsg with the value of the string parameter.

Syntax 2

TXBase(const TXBase& src);

Description

Creates a copy of the TXBase object passed in the TXBase parameter.

Destructor

virtual ~TXBase;

Description

Destroys  the TXBase object and decrements the InstanceCount data member.


See Also

TXOwl Public Constructors and Destructor


TXBase::Clone

TXBase

Syntax

virtual TXBase* Clone();

Description

Makes a copy of the exception object.


TXBase::Throw

TXBase

Syntax

virtual void Throw();

Description

Throws the exception object.


TXCompatibility Class

OWL Hierarchy	Inheritance

Header File

except.h

Description

Describes an exception that results from setting TModule::Status to nonzero. This exception is included for backward compatibility with ObjectWindows 1.0.

Public Constructors

TXCompatibility(int statusCode);

TXCompatibility(const TXCompatibility& src);

Public Member Functions

TXOwl* Clone();

static string MapStatusCodeToString(int statusCode);

void Throw();

int Unhandled(TModule* app, unsigned promptResId);


TXCompatibility Public Constructors

TXCompatibility

Form 1

TXCompatibility(int statusCode);

Form 2

TXCompatibility(const TXCompatibility& src);

Description

Form 1: Constructs a TXCompatibility object.

Form 2: Constructs a TXCompatibility object with the window that failed.


TXCompatibility::Clone

TXCompatibility

Syntax

TXOwl* Clone();

Description

Makes a copy of the exception object. Clone must be implemented in any class derived from TXOwl.


TXCompatibility::MapStatusCodeToString

TXCompatibility

Syntax

static string MapStatusCodeToString(int statusCode);

Description

Retrieves Tmodule's status code and coverts it to a string.


TXCompatibility::Throw

TXCompatibility

Syntax

void Throw();

Description

Throws the exception object. Throw must be implemented in any class derived from TXOwl.


TXCompatibility::Unhandled

TXCompatibility

Syntax

int Unhandled(TModule* app, unsigned promptResId);

Description

If an exception caught in the message loop has not been handled, Unhandled is called. Unhandled deletes the window. This type of exception could occur if a window can't be created.


TMenu::TXMenu class

OWL Hierarchy	Inheritance

Header File

menu.h

Description

A nested class, TXMenu describes an exception that occurs when a menu item cannot be constructed.

Public Constructors

TXMenu(unsigned resId = IDS_GDIFAILURE);

Public member functions

TXOwl* Clone();

void Throw();


TMenu Public constructors
TXMenu Public constructors

TXMenu

Syntax

TXMenu(unsigned resId = IDS_GDIFAILURE);

Description

Constructs a TXMenu exception object with a default IDS_GDIFAILURE message.


TXMenu::Clone

TXMenu

Syntax

TXOwl* Clone();

Description

Makes a copy of the exception object.


TXMenu::Throw

TXMenu

Syntax

void Throw();

Description

Throws a TXMenu exception.


TXOutOfMemory Class

OWL Hierarchy	Inheritance

Header File

except.h

Description

Describes an exception that results from running out of memory.

Public constructors

TXOutOfMemory();

Public member functions

TXOwl* Clone();

void Throw();


TXOutOfMemory Public constructors

TXOutOfMemory

Syntax

TXOutOfMemory();

Description

Constructs a TXOutOfMemory object.


TXOutOfMemory Clone
TXOutOfMemory::Clone

TXOutOfMemory

Syntax

TXOwl* Clone();

Description

Makes a copy of the exception object. Clone must be implemented in any class derived from TXOwl.


TXOutOfMemory::Throw

TXOutOfMemory

Syntax

void Throw();

Description

Throws the exception object. Throw must be implemented in any class derived from TXOwl.


TXOwl Class

See Also	OWL Hierarchy	Inheritance

Header File

except.h

Description

TXOwl is a parent class for several classes designed to describe exceptions. In most cases, you derive a new class from TXOwl instead of using this one directly. The ObjectWindows classes derived from TXOwl include

Class	Description

TXCompatibility	Describes an exception that occurs if  TModule::Status is not zero

TValidator::TXValidator	Describes an exception that occurs if there is an invalid validator expression

TWindow::TXWindow	Describes an exception that results from trying to create an invalid window

TGdiObject::TXGdi	Describes an exception that results from creating an invalid GDI object

TApplication::TXInvalidMainWindow	Describes an exception that results from creating an invalid main window

TMenu::TXMenu	Describes an exception that occurs when a menu object is invalid

TModule::TXInvalidModule	Describes an exception that occurs if a TModule object is invalid

TPrinter::TXPrinter	Describes an exception that occurs if a printer device context is invalid

TXOutOfMemory	Describes an exception that occurs if an out of memory error occurs

Each of the exception classes describes a particular type of exception. When your program encounters a given situation that's likely to produce this exception, it passes control to the specified exception-handling object. If you use exceptions in your code, you can avoid having to scatter error-handling procedures throughout your program.

To create an exception handler, place the keyword try before the block of code that might produce the abnormal condition (the code that might generate an exception object) and the keyword catch before the block of code that follows the try block. If an exception is thrown within the try block, the classes within each of the subsequent catch clauses are checked in sequence. The first one that matches the class of the exception object is executed.

The following example from MDIFILE.CPP, a sample program on your distribution disk, shows how to set up a try/catch block around the code that might throw an exception.

void TMDIFileApp::CmRestoreState()

{

   char* errorMsg = 0;

   ifpstream is(DskFile);

   if (is.bad())

      errorMsg = "Unable to open desktop file.";

// try block of code //

   else {

   if (Client->CloseChildrenParen) {

      try {

         is >>* this;

         if (is.bad())

            errorMsg = "Error reading desktop file.";

         else

             Client->CreateChildren();

     }

// catch block of code //

   catch (xalloc) {

      Client->CloseChildren();

      errorMsg = "Not enough memory to open file.";

    }

   }

 }

 if (errorMsg)

   MainWindow->MessageBox(errorMsg, "Error",
      MB_OK | MB_ICONEXCLAMATION);

}

Public Data Member

unsigned ResId;

Public Constructors and Destructor

TXOwl(const string& msg, unsigned resId = 0);

TXOwl(unsigned resId, TModule* module=::module);

~TXOwl();

Public Member Functions

TXOwl* Clone();

unsigned GetErrorCode() const;

static string ResourceIdToString(bool* found, unsigned resId, TModule* module = ::module);

void Throw();

virtual int Unhandled(TModule* app, unsigned promptResId);


Abnormal conditions outside the program's control


See Also

TXBase


TXOwl::ResId

TXOwl

Syntax

unsigned ResId;

Description

Resource ID for a TXOwl object.


TXOwl Public Constructors and Destructor

TXOwl

Syntax 1

TXOwl(const string& msg, unsigned resId = 0);

Description

Form 1: Constructs a TXOwl object with a string message (msg).

Syntax 2

TXOwl(unsigned resId, TModule* module = ::module);

Description

Form 2: Loads the string resource identified by the resId parameter and uses this resId to initialize the TXBase object.

Destructor

~TXOwl();

Description

Destroys a TXOwl object.


TXOwl::Clone

TXOwl

Syntax

TXOwl* Clone();

Description

Makes a copy of the exception object. Clone must be overridden in any class derived from TXOwl.


TXOwl::GetErrorCode

TXOwl

Syntax

unsigned GetErrorCode() const;

Description

Returns the resource ID.


TXOwl::ResourceIdToString

TXOwl

Syntax

static string ResourceIdToString(bool* found, unsigned resId, TModule* module = ::module);

Description

Converts the resource ID to a string and returns a string that identifies the exception. If the string message cannot be loaded, returns a "not found" message. Sets the found parameter to TRUE if the resource is located; otherwise, sets found to FALSE.


TXOwl::Throw

TXOwl

Syntax

void Throw();

Description

Throws the exception object. Throw must be implemented in any class derived from TXOwl.


TXOwl::Unhandled

TXOwl

Syntax

virtual int Unhandled(TModule* app, unsigned promptResId);

Description

Called when an unhandled exception is caught at the main message loop level.


vnxxxx View Notification Constants

See Also

Header File

docview.h

Description

The view notification constants are used to notify the view of a given event.

Constant	Meaning

vnCommit	Changes are committed to the document.

vnCustomBase	Base event for document notifications.

vnDocOpened  	Document has been opened.

vnDocClosed  	Document has been closed.

vnIsDirty 	Is true if uncommitted changes are present.

vnInvalidate	Is true if uncommitted changes are present.

vnIsWindow 	Is true if the HWND passed belongs to this view.

vnRevert	Document's previous data is reloaded and overwrites the view's current data.

vnViewOpened	A new view has been constructed.

vnViewClosed    	A view is about to be destroyed.


See Also

TListView

TEditView


ABC struct

Header File

windows.h

Syntax

typedef struct _ABC {

 int abcA;

 UINT abcB;

 int abcC;

} ABC;

Description

The ABC structure contains the width of a character in a TrueType® font.

Member	Description

abcA	"A" character spacing. "A" spacing is the distance to add to the current position before drawing the character glyph.

abcB	"B" character spacing. "B" spacing is the width of the drawn portion of the character glyph.

abcC	"C" character spacing. "C" spacing is the distance to add to the current position to provide white space to the right of the character glyph.

The total width of a character is the sum of abcA, abcB, and abcC . Either the abcA or abcC can be negative to indicate underhangs or overhangs.


BITMAP struct

Header File

windows.h

Syntax

16-bit version:

typedef struct tagBITMAP {

 int bmType;

 int bmWidth;

 int bmHeight;

 int bmWidthBytes;

 BYTE bmPlanes;

 BYTE bmBitsPixel;

 void FAR* bmBits;

} BITMAP;

32-bit version:

typedef struct tagBITMAP {

 LONG bmType;

 LONG bmWidth;

 LONG bmHeight;

 LONG bmWidthBytes;

 WORD bmPlanes;

 WORD bmBitsPixel;

 LPVOID bmBits;

} BITMAP;

Description

BITMAP defines the height, width, color format, and bit values of a logical bitmap.

Member	Description

bmType	Bitmap type. For logical bitmaps, this member must be zero.

bmWidth	Bitmap width in pixels. Must be greater than zero.

bmHeight	Bitmap height in raster lines. Must be greater than zero.

bmWidthBytes	Number of bytes per raster line. Must be an even number because the graphics device interface (GDI) assumes that the bit values of a bitmap form an array of integer (two-byte) values.

bmPlanes	Number of bitmap color planes.

bmBitsPixel	Number of adjacent color bits on each plane needed to define a pixel.

bmBits	Points to the location of the bitmap bit values. Must be a long pointer to an array of one-byte values.

Currently used bitmap formats are monochrome and color. Monochrome bitmaps use a one-bit, one-plane format. Each scan is a multiple of 16 bits or 32 bits. A monochrome bitmap of height n is organized as follows:

Scan 0

Scan 1

  ...

Scan n-2

Scan n-1

Monochrome device pixels are black or white. If a bitmap bit is 1, the corresponding pixel is turned on (white). If a bitmap is 0, the corresponding pixel is turned off (black).


BITMAPCOREHEADER struct

See Also

Header File

windows.h

Syntax

typedef struct tagBITMAPCOREHEADER {

 DWORD bcSize;

 WORD bcWidth;

 WORD bcHeight;

 WORD bcPlanes;

 WORD bcBitCount;

} BITMAPCOREHEADER;

Description

Contains device-independent bitmap (DIB) dimension and color-format information.

Member	Description

bcSize	Number of bytes required by the structure.

bcWidth	Width of the bitmap, in pixels.

bcHeight	Height of the bitmap, in pixels.

bcPlanes	Number of planes for the target device. Must be 1.

bcBitCount	Number of bits per pixel. Must be 1, 4, 8, or 24.

This structure is combined with a color table in the BITMAPCOREINFO structure to provide a complete definition of the dimensions and colors of a DIB.


See Also

BITMAPCOREINFO struct

RGBTRIPLE struct


BITMAPCOREINFO
BITMAPCOREINFO struct

Header File

windows.h

Syntax

typedef struct _BITMAPCOREINFO {

 BITMAPCOREHEADER bmciHeader;

 RGBTRIPLE bmciColors[1];

} BITMAPCOREINFO;

Description

Defines the dimensions and color information for a device-independent bitmap (DIB).

Member	Description

bmciHeader	Structure containing DIB color and dimension information.

bmciColors	Structure defining bitmap colors.

A DIB consists of two parts: a BITMAPCOREINFO structure describing the dimensions and colors of the bitmap, and an array of bytes defining the pixels of the bitmap. The bits in the array are packed together, but each scan line must be padded with zeroes to end on a LONG boundary. The origin of the bitmap is the lower left corner.

The bcBitCount member of the BITMAPCOREHEADER structure determines the number of bits that define each pixel and the maximum number of colors in the bitmap. This member can be one of the following values:

Value	Description

1	The bitmap is monochrome, and the bmciColors member contains two entries. Each bit in the bitmap array represents a pixel. If the bit is clear, the pixel is displayed with the color of the first entry in the bmciColors table; if the bit is set, the pixel has the color of the second entry in the table.

4	The bitmap has a maximum of 16 colors, and the bmciColors member contains up to 16 entries. Each pixel in the bitmap is represented by a 4-bit index into the color table. For example, if the first byte in the bitmap is 0x1F, the byte represents two pixels. The first pixel contains the color in the second table entry, and the second pixel contains the color in the sixteenth table entry.

8	The bitmap has a maximum of 256 colors, and the bmciColors member contains up to 256 entries. In this case, each byte in the array represents a single pixel.

24	The bitmap has a maximum of 224 colors, and the bmciColors member is NULL. Each 3-byte triplet in the bitmap array represents the relative intensities of red, green, and blue, respectively, for a pixel.

The colors in the bmciColors table should appear in order of importance.

Alternatively, for functions that use DIBs, the bmciColors member can be an array of 16-bit unsigned integers that specify indexes into the currently realized logical palette, instead of explicit RGB values. In this case, an application using the bitmap must call the DIB functions (CreateDIBitmap, CreateDIBPatternBrush, and CreateDIBSection) with the iUsage parameter set to DIB_PAL_COLORS.

Note:The bmciColors member should not contain palette indexes if the bitmap is to be stored in a file or transferred to another application. Unless the application has exclusive use and control of the bitmap, the bitmap color table should contain explicit RGB values.


BITMAPINFO struct

Header File

windows.h

Syntax

16-bit version:

typedef struct tagBITMAPINFO {

 BITMAPINFOHEADER bmiHeader;

 RGBQUAD bmiColors[1];

} BITMAPINFO;

Description

Defines the dimensions and color information for a device-independent bitmap (DIB).

Member	Description

bmiHeader	Structure containing DIB dimension and color-format information.

bmiColors	Structures that defines bitmap colors.

A DIB consists of a BITMAPINFO structure, which describes the dimensions and colors of the bitmap, and an array of bytes defining the bitmap pixels. The array bits are packed together, but each scan line must be zero-padded to end on a LONG boundary. Segment boundaries can appear anywhere in the bitmap. The bitmap origin is the lower-left corner.

The biBitCount member of the BITMAPINFOHEADER structure determines the number of bits which define each pixel and the maximum number of colors in the bitmap. This member may be set to any of the following values:

Value	Description

1	The bitmap is monochrome, and the bmciColors member must contain two entries. Each bit in the bitmap array represents a pixel. If the bit is clear, the pixel is displayed with the color of the first entry in the bmciColors table. If the bit is set, the pixel has the color of the second entry in the table.

4	The bitmap has a maximum of 16 colors, and the bmciColors member contains 16 entries. Each pixel in the bitmap is represented by a four-bit index into the color table. For example, if the first byte in the bitmap is 0x1F, the byte represents two pixels. The first pixel contains the color in the second table entry, and the second pixel contains the color in the sixteenth table entry.

8	The bitmap has a maximum of 256 colors, and the bmciColors member contains 256 entries. In this case, each byte in the array represents a single pixel.

16	The bitmap has a maximum of 2^16 colors. The biCompression member of the BITMAPINFOHEADER must be BI_BITFIELDS. The bmiColors member contains 3 DWORD color masks which specify the red, green, and blue components, respectively, of each pixel. Bits set in the DWORD mask must be contiguous and should not overlap the bits of another mask. All the bits in the pixel do not have to be used. Each WORD in the array represents a single pixel.

24	The bitmap has a maximum of 224 colors. The bmciColors member is NULL, and each 3-byte sequence in the bitmap array represents the relative intensities of red, green, and blue, respectively, of a pixel.

32	The bitmap has a maximum of 232 colors. The biCompression member of the BITMAPINFOHEADER must be BI_BITFIELDS. The bmiColors member contains 3 DWORD color masks which specify the red, green, and blue components, respectively, of each pixel. Bits set in the DWORD mask must be contiguous and should not overlap the bits of another mask. All the bits in the pixel do not have to be used. Each DWORD in the array represents a single pixel.

The biClrUsed member of the BITMAPINFOHEADER structure specifies the number of color indexes in the color table actually used by the bitmap. If the biClrUsed member is set to zero, the bitmap uses the maximum number of colors corresponding to the value of the biBitCount member. The colors in the bmiColors table should appear in order of importance.

Alternatively, for functions that use DIBs, the  bmiColors  member can be an array of 16-bit unsigned integers that specify an index into the currently realized logical palette instead of explicit RGB values. In this case, an application using the bitmap must call DIB functions ( CreateDIBitmap ,  CreateDIBPatternBrush , and  CreateDIBSection )with the wUsage parameter set to DIB_PAL_COLORS.

Note:	The  bmiColors  member should not contain palette indexes if the bitmap is to be stored in a file or transferred to another application. Unless the application uses the bitmap exclusively and under its complete control, the bitmap color table should contain explicit RGB values.


BITMAPINFOHEADER struct

Header File

windows.h

Syntax

typedef struct tagBITMAPINFOHEADER {

 DWORD biSize;

 LONG biWidth;

 LONG biHeight;

 WORD biPlanes;

 WORD biBitCount;

 DWORD biCompression;

 DWORD biSizeImage;

 LONG biXPelsPerMeter;

 LONG biYPelsPerMeter;

 DWORD biClrUsed;

 DWORD biClrImportant;

} BITMAPINFOHEADER;

Description

Contains dimension and color-format information for device-independent bitmaps (DIB).

Member	Description

biSize	Number of bytes required by this structure.

biWidth	Width of the bitmap, in pixels.

biHeight	Height of the bitmap, in pixels. If biHeight is negative, the bitmap origin is the upper-left corner and the height is the absolute value of biHeight.

biPlanes	Specifies the number of planes for the target device. This member must be set to 1.

biBitCount	Specifies the number of bits per pixel. This value must be 1, 4, 8, 16 (16-bit only), 24, or 32 (32-bit only).

biCompression	Specifies the type of compression for a compressed bitmap. It can be one of the following values:

Value	Meaning

BI_RGB	Uncompressed.

BI_RLE8	Specifies a run-length encoded format for bitmaps with 8 bits per pixel.

BI_RLE4	Specifies a run-length encoded format for bitmaps with 4 bits per pixel.

BI_BITFIELDS	Specifies the bitmap is not compressed and the color table consists of 3 DWORD color masks which specify the red, green, and blue components, respectively, of each pixel. This is valid when used with 16 and 32 bits per pixel bitmaps.

biSizeImage	Size of the image, in bytes. Can be 0 if the bitmap is in the BI_RGB format.

biXPelsPerMeter	Specifies the horizontal resolution, in pixels per meter, of the target device for the bitmap. Use this value to select a bitmap from a resource group that best matches the characteristics of the current device.

biYPelsPerMeter	Specifies the vertical resolution, in pixels per meter, of the target device.

biClrUsed	Specifies the number of color indexes in the color table actually used by the bitmap. If this value is 0, the bitmap uses the maximum number of colors corresponding to the value of the biBitCount member.

For 16-bit applications, if biClrUsed is nonzero, it specifies the actual number of colors that the graphics engine or device driver will access if the biBitCount member is less than 24. If biBitCount is set to 24, biClrUsed specifies the size of the reference color table used to optimize performance of color palettes.

For 32-bit applications, if biClrUsed is nonzero and the biBitCount member is less than 16, the biClrUsed member specifies the actual number of colors the graphics engine or device driver accesses. If biBitCount is 16 or greater, then biClrUsed member specifies the size of the color table used to optimize performance of Windows color palettes. For biBitCount equal to 16 or 32 the optimal color palette starts immediately following the 3 DWORD masks.

If the bitmap is a packed bitmap (that is, a bitmap in which the bitmap array immediately follows the BITMAPINFO header and which is referenced by a single pointer), the biClrUsed member must be set to zero or to the actual size of the color table.

biClrImportant	Specifies the number of color indexes that are considered important for displaying the bitmap. If this value is zero, all colors are important.


COLORREF typedef

Header File

windows.h

Syntax

typedef DWORD COLORREF;

Description

A 32-bit value used to specify an RGB color. The COLORREF value has the following hexadecimal form:

0x00bbggrr

The low-order byte (rrcontains a value for the relative intensity of red; the second byte (ggcontains a value for green; and the third byte (bbcontains a value for blue. The fourth byte byte must be zero. The RGB macro can be used to set these values:

RGB(red, green, blue)

Each color parameter can range from 0x0 to 0xFF.


COMPAREITEMSTRUCT struct

Header File

windows.h

Syntax

typedef struct tagCOMPAREITEMSTRUCT {

 UINT  CtlType;

 UINT  CtlID;

 HWND  hwndItem;

 UINT  itemID1;

 DWORD itemData1;

 UINT  itemID2;

 DWORD itemData2;

} COMPAREITEMSTRUCT;

Description

Supplies the identifiers and application-supplied data for two items in a sorted owner-draw list box or combo box. The table below describes the members.

Member	Description

CtlType	Either ODT_LISTBOX for an owner-drawn list box, or ODT_COMBOBOX for an owner-drawn combo box.

CtlID	List box or combo box identifier.

hwndItem	Control identifier.

itemID1	Index of the first item in the list box or combo box being compared.

itemData1	Application-supplied data for the first item being compared.

itemID2	Index of the second item in the list box or combo box being compared.

itemData2	Application-supplied data for the second item being compared.


DELETEITEMSTRUCT struct

Header File

windows.h

Syntax

typedef struct tagDELETEITEMSTRUCT {

 UINT CtlType;

 UINT CtlID;

 UINT itemID;

 HWND hwndItem;

 UINT itemData;

} DELETEITEMSTRUCT;

Describes a deleted owner-drawn list-box or combo-box item. The table below describes the members.

Member	Description

CtlType	Either ODT_LISTBOX for an owner-drawn list box, or ODT_COMBOBOX for an owner-drawn combo box.

CtlID	List box or combo box identifier.

itemID	Index of the item in the list box or combo box being removed.

hwndItem	Control indentifier.

itemData	Application-defined item data.


DEVMODE struct

Header File

windows.h

Syntax

16-bit version:

typedef struct tagDEVMODE {

 char  dmDeviceName[CCHDEVICENAME];

 UINT  dmSpecVersion;

 UINT  dmDriverVersion;

 UINT  dmSize;

 UINT  dmDriverExtra;

 DWORD dmFields;

 int   dmOrientation;

 int   dmPaperSize;

 int   dmPaperLength;

 int   dmPaperWidth;

 int   dmScale;

 int   dmCopies;

 int   dmDefaultSource;

 int   dmPrintQuality;

 int   dmColor;

 int   dmDuplex;

 int   dmYResolution;

 int   dmTTOption;

} DEVMODE;

32-bit version:

typedef struct _devicemode {

 TCHAR  dmDeviceName[32];

 WORD   dmSpecVersion;

 WORD   dmDriverVersion;

 WORD   dmSize;

 WORD   dmDriverExtra;

 DWORD  dmFields;

 short  dmOrientation;

 short  dmPaperSize;

 short  dmPaperLength;

 short  dmPaperWidth;

 short  dmScale;

 short  dmCopies;

 short  dmDefaultSource;

 short  dmPrintQuality;

 short  dmColor;

 short  dmDuplex;

 short  dmYResolution;

 short  dmTTOption;

 short  dmCollate;

 TCHAR  dmFormName[32];

 WORD   dmUnusedPadding;

 USHORT dmBitsPerPel;

 DWORD  dmPelsWidth;

 DWORD  dmPelsHeight;

 DWORD  dmDisplayFlags;

 DWORD  dmDisplayFrequency;

} DEVMODE;

Description

Contains printer-driver initialization and environment data. The table below describes each member.

Member	Description

dmDeviceName	Name of the device the driver supports--for example.

dmSpecVersion	Version number of this structure.

dmDriverVersion	Printer driver version number.

dmSize	Size of this structure, in bytes,excluding dmDriverData. Use to find the length of the structure without having to account for different versions.

dmDriverExtra	Size of the optional dmDriverData member, in bytes. If an application does not use device-specific information, it should set this member to zero.

dmFields	Contains flags that indicate which of the remaining members in this structure have been initialized. It can be any combination of the following values:

DM_ORIENTATION	DM_DEFAULTSOURCE

DM_PAPERSIZE	DM_PRINTQUALITY

DM_PAPERLENGTH	DM_COLOR

DM_PAPERWIDTH	DM_DUPLEX

DM_SCALE	DM_YRESOLUTION

DM_COPIES	DM_TTOPTION

dmOrientation	Paper orientation. Can be DMORIENT_PORTRAIT or DMORIENT_LANDSCAPE.

dmPaperSize	Paper size. Can be set to zero if the length and width of the paper are specified by dmPaperLength and dmPaperWidth. Otherwise, set to one of the following values:

Value	Meaning

DMPAPER_FIRST	DMPAPER_LETTER

DMPAPER_LETTER	Letter, 8 1/2 x 11 in.

DMPAPER_LETTERSMALL	Letter Small,
8 1/2 x 11 in.

DMPAPER_TABLOID	Tabloid, 11 x 17 in.

DMPAPER_LEDGER	Ledger, 17 x 11 in.

DMPAPER_LEGAL	Legal, 8 1/2 x 14 in.

DMPAPER_STATEMENT	Statement,
5 1/2 x 8 1/2 in.

DMPAPER_EXECUTIVE	Executive,
7 1/2 x 10 1/2 in.

DMPAPER_A3	A3, 297 x 420 mm

DMPAPER_A4	A4, 210 x 297 mm

DMPAPER_A4SMALL	A4 Small,
210 x 297 mm

DMPAPER_A5	A5, 148 x 210 mm

DMPAPER_B4	B4, 250 x 354 mm

DMPAPER_B5	B5, 182 x 257 mm

DMPAPER_FOLIO	Folio, 8 1/2 x 13 in.

DMPAPER_QUARTO	Quarto, 215 x 275 mm

DMPAPER_10X14	10 x 14 in

DMPAPER_11X17	11 x 17 in.

DMPAPER_NOTE	Note, 8 1/2 x 11 in.

DMPAPER_ENV_9	Envelope #9,
3 7/8 x 8 7/8 in.

DMPAPER_ENV_10	Envelope #10,
4 1/8 x 9 1/2 in.

DMPAPER_ENV_11	Envelope #11,
4 1/2 x 10 3/8 in.

DMPAPER_ENV_12	Envelope #12,
4 1/2 x 11 in.

DMPAPER_ENV_14	Envelope #14,
5 x 11 1/2 in.

DMPAPER_CSHEET	C size sheet

DMPAPER_DSHEET	D size sheet

DMPAPER_ESHEET	E size sheet

DMPAPER_ENV_DL	Envelope DL,
110 x 220 mm

DMPAPER_ENV_C3	Envelope C3,
324 x 458 mm

DMPAPER_ENV_C4	Envelope C4,
229 x 324 mm

DMPAPER_ENV_C5	Envelope C5,
162 x 229 mm

DMPAPER_ENV_C6	Envelope C6,
114 x 162 mm

DMPAPER_ENV_C65	Envelope C65,
114 x 229 mm

DMPAPER_ENV_B4	Envelope B4,
250 x 353 mm

DMPAPER_ENV_B5	Envelope B5,
176 x 250 mm

DMPAPER_ENV_B6	Envelope B6,
176 x 125 mm

DMPAPER_ENV_ITALY	Envelope,
110 x 230 mm

DMPAPER_ENV_MONARCH	Envelope Monarch,
3 7/8 x 7 1/2 in.

DMPAPER_ENV_PERSONAL	Envelope,
3 5/8 x 6 1/2 in.

DMPAPER_FANFOLD_US	U.S. Standard Fanfold, 14 7/8 x 11 in.

DMPAPER_FANFOLD_STD_GERMAN	German Standard Fanfold,
8 1/2 x 12 in.

DMPAPER_FANFOLD_LGL_GERMAN	German Legal Fanfold,
8 1/2 x 13 in.

DMPAPER_LAST	German Legal Fanfold,
8 1/2 x 13 in.

DMPAPER_USER	User-defined

dmPaperLength	Paper length, in tenths of a millimeter. Overrides dmPaperSize.

dmPaperWidth	Paper width, in tenths of a millimeter, Overrides dmPaperSize.

dmScale	Print output scale factor. Apparent page size is scaled from the physical page size by dmScale/100.

dmCopies	Specifies the number of copies printed if the device supports multiple-page copies.

dmDefaultSource	Default paper feed bin. This member can be one of the following values:

DMBIN_AUTO	DMBIN_LOWER

DMBIN_CASSETTE	DMBIN_MANUAL

DMBIN_ENVELOPE	DMBIN_MIDDLE

DMBIN_ENVMANUAL	DMBIN_ONLYONE

DMBIN_FIRST	DMBIN_SMALLFMT

DMBIN_LARGECAPACITY	DMBIN_TRACTOR

DMBIN_LARGEFMT	DMBIN_UPPER

DMBIN_LAST

mPrintQuality	Printer resolution. Can be one of the following values:

DMRES_HIGH

DMRES_MEDIUM

DMRES_LOW

DMRES_DRAFT

If another (positive) value is given, it specifies dots per inch (DPI) and is device-dependent. If the printer initializes dmYResolution, then dmPrintQuality specifies the x-resolution of the printer in DPI.

dmColor	Color or monochrome output. Can be DMCOLOR_COLOR, or DMCOLOR_MONOCHROME.

dmDuplex	Duplex (double-sided) printing for printers capable of duplex printing. This member can be one of the following values:

DMDUP_SIMPLEX

DMDUP_HORIZONTAL

DMDUP_VERTICAL

dmYResolution	Y-resolution of the printer in DPI. If the printer initializes dmYResolution, dmPrintQuality specifies the x-resolution of the printer, in DPI.

dmTTOption	TrueType-font printing. Can be one of the following values:

DMTT_BITMAP	Print TrueType fonts as graphics. The default for dot-matrix printers.

DMTT_DOWNLOAD	Download TrueType fonts as soft fonts. Default for Hewlett-Packard printers that use Printer Control Language (PCL).

DMTT_SUBDEV	Substitute device fonts for TrueType fonts. Default for PostScript printers.

dmUnusedPadding	(32-bit only) Used to align the structure on a DWORD boundary.

dmCollate	Collation when printing multiple copies. Can be be one of the following values:

DMCOLLATE_TRUE	Collate when printing multiple copies.

DMCOLLATE_FALSE	Do NOT collate when printing multiple copies.

dmFormName	(32-bit only) Specifies the name of the form to use; for example, "Letter" or "Legal".

dmBitsPerPel	(32-bit only) Color resolution of the display device, in bits per pixel.

dmPelsWidth	(32-bit only) Width of the visible device surface, in pixels.

dmPelsHeight	(32-bit only) Height of the visible device surface, in pixels.

dmDisplayFlags	(32-bit only) Device display mode. Can be one of the following values:

Value	Meaning

DM_GRAYSCALE	Non-color display. If this flag is not set, color is assumed.

DM_INTERLACED	Interlaced display mode. If the flag is not set, non-interlaced is assumed.

dmDisplayFrequency	(32-bit only) Specifies the display device frequency, in hertz.


DRAWITEMSTRUCT struct

Header File

windows.h

Syntax

typedef struct tagDRAWITEMSTRUCT {

 UINT CtlType;

 UINT CtlID;

 UINT itemID;

 UINT itemAction;

 UINT itemState;

 HWND hwndItem;

 HDC hDC;

 RECT rcItem;

 DWORD itemData;

} DRAWITEMSTRUCT;

Description

Provides information the owner window must have to determine how to paint an owner-drawn control or menu item. The owner window of the owner-drawn control or menu item receives a pointer to this structure as the lParam parameter of the WM_DRAWITEM message.

Member	Description

CtlType	Specifies the control type. This member can be one of the following values:

ODT_BUTTON	Owner-drawn button

ODT_COMBOBOX	Owner-drawn combo box

ODT_LISTBOX	Owner-drawn list box

ODT_MENU	Owner-drawn menu item

CtlID	Specifies the identifier of the combo box, list box, or button. This member is not used for a menu item.

itemID	Specifies the menu item identifier for a menu item or the index of the item in a list box or combo box. For an empty list box or combo box, this member can be -1. This allows the application to draw only the focus rectangle at the coordinates specified by the rcItem member even though there are no items in the control. This indicates to the user whether the list box or combo box has the focus. How the bits are set in the itemAction member determines whether the rectangle is to be drawn as though the list box or combo box has the focus.

itemAction	Specifies the drawing action required. This member can be one or more of the following values:

ODA_DRAWENTIRE	The entire control needs to be drawn.

ODA_FOCUS	The control has lost or gained the keyboard focus. The itemState member should be checked to determine whether the control has the focus.

ODA_SELECT	The selection status has changed. The itemState member should be checked to determine the new selection state.

itemState	Specifies the visual state of the item after the current drawing action takes place. This member can be a combination of the following values:

ODS_CHECKED	The menu item is to be checked. This bit is used only in a menu.

ODS_DISABLED	The item is to be drawn as disabled.

ODS_FOCUS	The item has the keyboard focus.

ODS_GRAYED	The item is to be grayed. This bit is used only in a menu.

ODS_SELECTED	The menu item's status is selected.

hwndItem	Identifies the control for combo boxes, list boxes, and buttons. For menus, this member identifies the menu containing the item.

hDC	Identifies a device context (DC); this DC must be used when performing drawing operations on the control.

rcItem	Specifies a rectangle that defines the boundaries of the control to be drawn. This rectangle is in the DC specified by the hDC member. Anything the owner window draws in the DC for combo boxes, list boxes, and buttons is automatically clipped, except for menu items. When drawing menu items, the owner window must not draw outside the boundaries of the rectangle defined by the rcItem member.

itemData	Specifies the application-defined 32-bit value associated with the menu item. For a control, this parameter specifies the value last assigned to the list box or combo box by the LB_SETITEMDATA or CB_SETITEMDATA message. If the list box or combo box has the LBS_HASSTRINGS or CBS_HASSTRINGS style, this value is initially zero. Otherwise, this value is initially the value that was passed to the list box or combo box in the lParam parameter of one of these messages: CB_ADDSTRING, CB_INSERTSTRING, LB_ADDSTRING, LB_INSERTSTRING.


FINDREPLACE struct

Header File

windows.h

Syntax

typedef struct {

 DWORD        lStructSize;

 HWND         hwndOwner;

 HINSTANCE    hInstance;

 DWORD        Flags;

 LPSTR        lpstrFindWhat;

 LPSTR        lpstrReplaceWith;

 WORD         wFindWhatLen;

 WORD         wReplaceWithLen;

 DWORD        lCustData;

 LPFRHOOKPROC lpfnHook;

 LPCSTR       lpTemplateName;

} FINDREPLACE;

Description

Contains initialization information to initialize the system-defined find-and-replace dialog boxes. The table below describes the members.

Member	Description

lStructSize	Length, in bytes, of the structure.

hwndOwner	Window that owns the dialog box. Can be any valid window handle, but must not be NULL.

hInstance	Data block that contains a dialog box template specified by lpstrTemplateName. Used only if the Flags member is set to FR_ENABLETEMPLATE; otherwise ignored.

Flags	Dialog box initialization flags. Can be a combination of the following values:

Value	Meaning

FR_DIALOGTERM	Indicates that the dialog box is closing.

FR_DOWN	If this flag is set, the search direction is down; if the flag is clear, the search direction is up.

FR_ENABLEHOOK	Enables the hook function specified in the lpfnHook member of this structure. Used to initialize the dialog box only.

FR_ENABLETEMPLATE	Create the dialog box by using the dialog box template identified by the hInstance and lpTemplateName members. This flag is used to initialize the dialog box only.

FR_ENABLETEMPLATEHANDLE	Indicates that the hInstance member identifies a data block that contains a preloaded dialog box template. The lpTemplateName member is ignored if this flag is specified.

FR_FINDNEXT	The application should search for the next occurrence of the string specified by the lpstrFindWhat member.

FR_HIDEUPDOWN	Hides the Direction check box and the Up and Down controls.

FR_HIDEMATCHCASE	Hides the Match Case check box.

FR_HIDEWHOLEWORD	Hides the Match Whole Word Only check box.

FR_MATCHCASE	Case-sensitive searches.

FR_NOMATCHCASE	Disables the Match Case check box.

FR_NOUPDOWN	Disables the direction radio buttons.

FR_NOWHOLEWORD	Disables the Whole Word check box.

FR_REPLACE	Replace the current occurrence of the string specified by lpstrFindWhat with the string specified by lpstrReplaceWith.

FR_REPLACEALL	Replace all occurrences of the string specified by lpstrFindWhat member with the string specified by lpstrReplaceWith.

FR_SHOWHELP	Show the Help button. The hwndOwner member must not be NULL if this option is specified.

FR_WHOLEWORD	Checks the Whole Word check box. Only whole words matching the search string will be considered.

lpstrFindWhat	String to search for. If there is a string specified when the dialog box starts, the dialog box initializes the Find What: text control with this string. If the FR_FINDNEXT flag is set when the dialog box is opened, the application should search for an occurrence of this string by using the FR_DOWN, FR_WHOLEWORD, and FR_MATCHCASE flags to further define the direction and type of search. The application must allocate a buffer for the string, which should be at least 80 characters long.

lpstrReplaceWith	Replacement string for replace operations.

wFindWhatLen	Length, in bytes, of the buffer pointed to by lpstrFindWhat.

wReplaceWithLen	Length, in bytes, of the buffer pointed to by lpstrReplaceWith.

lCustData	Application-defined data the passed to the hook function identified lpfnHook.

lpfnHook	Points to a hook function that processes messages intended for the dialog box. An application must specify the FR_ENABLEHOOK flag in the Flags member to enable the function; otherwise, the system ignores this structure member. Should return FALSE to pass a message on to the standard dialog procedure, or TRUE to discard the message.

lpstrTemplateName	Points to a null-terminated string that names the dialog box template resource to be substituted for the standard dialog box template.


GLYPHMETRICS struct

Header File

windows.h

Syntax

typedef struct _GLYPHMETRICS {

 UINT gmBlackBoxX;

 UINT gmBlackBoxY;

 POINT gmptGlyphOrigin;

 short gmCellIncX;

 short gmCellIncY;

} GLYPHMETRICS;

Description

Contains information about the placement and orientation of a glyph in a character cell, specified in logical units.

Member	Description

gmBlackBoxX	Width of the smallest rectangle that completely encloses the glyph.

gmBlackBoxY	Height of the smallest rectangle that completely encloses the glyph.

gmptGlyphOrigin	The x- and y-coordinates of the upper left corner of the smallest rectangle that completely encloses the glyph.

gmCellIncX	The horizontal distance from the origin of the current character cell to the origin of the next character cell.

gmCellIncY	The vertical distance from the origin of the current character cell to the origin of the next character cell.


HANDLETABLE struct

Header File

windows.h

Syntax

typedef struct tagHANDLETABLE {

 HGDIOBJ objectHandle[1];

} HANDLETABLE;

Description

An array of handles that identify a graphics device interface (GDI) object.


ICONINFO struct

Header File

windows.h

Syntax

typedef struct _ICONINFO {

   BOOL    fIcon;

   DWORD   xHotspot;

   DWORD   yHotspot;

   HBITMAP hbmMask;

   HBITMAP hbmColor;

} ICONINFO;

Description

The ICONINFO structure contains information about an icon or a cursor. The following table describes the members.

Member	Description

fIcon	Set to TRUE if this specifies an icon; FALSE if it specifies a cursor.

xHotspot	Specifies the x-coordinate of a cursor's hot spot. For icons the hot spot is always in the center, so this member is ignored.

yHotspot	Specifies the y-coordinate of the cursor's hot spot. For icons the hot spot is always in the center, so this member is ignored.

hbmMask	Specifies the icon bitmask bitmap. For black and white icons the upper half of hbmMask is the icon AND bitmask, the lower half is the icon XOR bitmask, and the height should be an even multiple of two. For color icons this mask defines the AND bitmask of the icon only.

hbmColor	Identifies the icon color bitmap. This member can be optional if this structure defines a black and white icon. After the AND bitmask of hbmMask is applied to the destination, the color bitmap is applied (using XOR) to the destination.


KERNINGPAIR struct

Header File

windows.h

Syntax

typedef struct tagKERNINGPAIR {

    WORD wFirst;

    WORD wSecond;

    int  iKernAmount;

} KERNINGPAIR;

Description

Defines a kerning pair. The following table describes the members.

Member	Description

wFirst	Character code for the first character in the kerning pair.

wSecond	Character code for the second character in the kerning pair.

iKernAmount	Amount this pair will be kerned if they appear side by side in the same font and size. This value is usually negative, and is given in logical units (depending on mapping mode).


LOGBRUSH struct

SeeAlso

Header File

windows.h

Syntax

typedef struct tagLOGBRUSH {

 UINT lbStyle;

 COLORREF lbColor;

 int lbHatch;

} LOGBRUSH;

Description

Defines the style, color, and pattern of a physical brush. The following table describes the member:

Member	Description

lbStyle	Specifies the brush style. This member can be one of the following values:

BS_DIBPATTERN	Pattern brush defined by a device-independent bitmap (DIB) specification.

BS_DIBPATTERNPT	A pattern brush defined by a device-independent bitmap (DIB) specification (32-bit only).

BS_HATCHED	Hatched brush.

BS_HOLLOW	Hollow brush.

BS_PATTERN	Pattern brush defined by a memory bitmap.

BS_NULL	Equivalent to BS_HOLLOW.

BS_SOLID	Solid brush.

lbColor	Specifies the color to draw the brush. If the lbStyle member is the BS_HOLLOW or BS_PATTERN value, lbColor is ignored.

If lpStyle is the BS_DIBPATTERN or BS_DIBPATTERNPT value, the low-order word of lbColor specifies whether the bmiColors members of the BITMAPINFO structure contain explicit RGB values or indexes into the currently realized logical palette. The lbColor member must be one of the following values:

DIB_PAL_COLORS	Color table consists of an array of 16-bit indexes into the currently realized logical palette.

DIB_RGB_COLORS	Color table contains literal RGB values.

lbHatch	Specifies a hatch style. The meaning depends on the brush style. If the lbStyle member is the BS_DIBPATTERN style, the lbHatch member contains a handle to a packed DIB. If the lbStyle member is the BS_DIBPATTERNPT style, the lbHatch member contains a pointer to a packed DIB.

If the lbStyle member is the BS_HATCHED style, the lbHatch member specifies the orientation of the lines used to create the hatch. This member can be one of the following values:

HS_BDIAGONAL	45-degree upward hatch (left to right)

HS_CROSS	Horizontal and vertical cross-hatch

HS_DIAGCROSS	45-degree cross-hatch

HS_FDIAGONAL	45-degree downward hatch (left to right)

HS_HORIZONTAL	Horizontal hatch

HS_VERTICAL	Vertical hatch

If the lbStylemember is the BS_PATTERN style, lbHatch must be a handle to the bitmap that defines the pattern. If the lbStyle member is the BS_SOLID or the BS_HOLLOW style, lbHatch is ignored.


See Also

BITMAPINFO struct


LOGFONT struct

Header File

windows.h

Syntax

typedef struct tagLOGFONT {

 int   lfHeight;

 int   lfWidth;

 int   lfEscapement;

 int   lfOrientation;

 int   lfWeight;

 BYTE  lfItalic;

 BYTE  lfUnderline;

 BYTE  lfStrikeOut;

 BYTE  lfCharSet;

 BYTE  lfOutPrecision;

 BYTE  lfClipPrecision;

 BYTE  lfQuality;

 BYTE  lfPitchAndFamily;

 BYTE  lfFaceName[LF_FACESIZE];

} LOGFONT;

32 bit version:

typedef struct tagLOGFONT { /* lf */

 LONG lfHeight;

 LONG lfWidth;

 LONG lfEscapement;

 LONG lfOrientation;

 LONG lfWeight;

 BYTE lfItalic;

 BYTE lfUnderline;

 BYTE lfStrikeOut;

 BYTE lfCharSet;

 BYTE lfOutPrecision;

 BYTE lfClipPrecision;

 BYTE lfQuality;

 BYTE lfPitchAndFamily;

 CHAR lfFaceName[LF_FACESIZE];

} LOGFONT;

Description

Defines font attributes. When creating a logical font, applications can use the default settings for most of the members. Unless lfHeight and lfFaceName are given specific values, the created logical font will be device dependent. The table below describes the members.

Member	Description

lfHeight	(16-bit applications) Font height, in logical units. If greater than zero, it specifies the font cell height. If less than zero, it specifies the character height of the font (applications that specify font height in points typically use a negative number for this member). If 0, the font mapper uses a default height. The font mapper chooses the largest physical font not exceeding the requested size,or the smallest font if the fonts exceed the requested size. The absolute value of the lfHeight member must not exceed 16,384 after it is converted to device units.

(32-bit applictions) Font height, in logical units. The font height can be specified in one of three ways. If lfHeight is greater than zero, it is transformed into device units and matched against the cell height of the available fonts. If it is zero, a reasonable default size is used. If it is less than zero, it is transformed into device units and the absolute value is matched against the character height of the available fonts. For all height comparisons, the font mapper looks for the largest font that does not exceed the requested size; if there is no such font, it looks for the smallest font available. This mapping occurs when the font is used for the first time.

lfWidth	Average font character width, in logical units, of font characters in logical units. If 0, the font mapper chooses a default width.

lfEscapement	Angle between the base line of a character and the x-axis, in tenths of degrees.

lfOrientation	Angle of character base line, tenths of degrees and relative to the bottom of the page.

lfWeight	Font weight. Can be one of the following values:

FW_DONTCARE	FW_SEMIBOLD

FW_THIN	FW_DEMIBOLD

FW_EXTRALIGHT	FW_BOLD

FW_ULTRALIGHT	FW_BOLD

FW_LIGHT	FW_ULTRABOLD

FW_NORMAL	FW_BLACK

FW_REGULAR	FW_HEAVY

FW_MEDIUM

If the value is 0, a default weight is used.

lfItalic	Italic font if TRUE.

lfUnderline	Underlined font if TRUE.

lfStrikeOut	Strikeout font if TRUE.

lfCharSet	Font character set. Can be one of the following values:

ANSI_CHARSET

DEFAULT_CHARSET (16 bit)

SYMBOL_CHARSET

SHIFTJIS_CHARSET (16 bit)

OEM_CHARSET

UNICODE_CHARSET (32 bit)

lfOutPrecision	Desired output precision. Specifies how closely the output must match the height, width, character orientation, escapement, and pitch of the requested font. Can be one of the following values:

OUT_CHARACTER_PRECIS	OUT_STRING_PRECIS

OUT_DEFAULT_PRECIS	OUT_STROKE_PRECIS

OUT_DEVICE_PRECIS   	OUT_TT_PRECIS

OUT_RASTER_PRECIS   	OUT_TT_ONLY_PRECIS

lfClipPrecision	Desired clipping precision. Specifies how to clip characters partially outside the clipping region. Can be any one of the following values:

CLIP_CHARACTER_PRECIS	CLIP_MASK

CLIP_DEFAULT_PRECIS	CLIP_STROKE_PRECIS

CLIP_EMBEDDED   	CLIP_TT_ALWAYS

CLIP_LH_ANGLES

To use an embedded read-only font, applications must specify the CLIP_EMBEDDED value.

To achieve consistent rotation of device, TrueType, and vector fonts, an application can use the OR operator to combine the CLIP_LH_ANGLES value with any of the other lfClipPrecision values. If the CLIP_LH_ANGLES bit is set, the rotation for all fonts is dependent on whether the orientation of the coordinate system is left-handed or right-handed. If CLIP_LH_ANGLES is not set, device fonts always rotate counter-clockwise, but the rotation of other fonts is dependent on the orientation of the coordinate system. (For more information about the orientation of coordinate systems, see the description of the lfEscapement member.)

lfQuality	Output font quality. Can be one of the following values:

Value	Meaning

DEFAULT_QUALITY	Font appearance does not matter.

DRAFT_QUALITY	Font appearance is less important than when the PROOF_QUALITY value is used.

PROOF_QUALITY	Font character quality is more important than matching logical-font attributes.

lfPitchAndFamily	Font family and pitch. The two low-order bits specify the font pitch and can be one of the following values:

DEFAULT_PITCH

FIXED_PITCH

VARIABLE_PITCH

The four high-order bits of the member specify the font family and can be one of the following values:

Value	Meaning

FF_DECORATIVE	Novelty fonts.

FF_DONTCARE	Don't care or don't know.

FF_MODERN	Fonts with constant stroke width, with or without serifs. (e.g. Pica and Courier)

FF_ROMAN	Fonts with variable stroke width and with serifs. (e.g. Times New Roman)

FF_SCRIPT	Fonts designed to look like handwriting (e.g. Script and Cursive)

FF_SWISS	Fonts with variable stroke width and without serifs.(e.g. Sans Serif)

Use the Boolean OR operator to match a pitch constant with a family constant.

lfFaceName	Specifies the typeface name of the font. The length of this string must not exceed LF_FACESIZE - 1.


LOGPALETTE struct

Header File

windows.h

Syntax

typedef struct tagLOGPALETTE {

 WORD palVersion;

 WORD palNumEntries;

 PALETTEENTRY palPalEntry[1];

} LOGPALETTE;

Description

Defines a logical color palette. Colors in the palette-entry table should appear in order of importance because entries earlier in the logical palette are more likely to be placed in the system palette. The following table describes the members:

Member	Description

palVersion	Specifies the Windows version number for the structure (currently 0x300).

palNumEntries	Specifies the number of entries in the logical color palette.

palPalEntry	Specifies an array of PALETTEENTRY structures that define the color and usage of each entry in the logical palette.


LOGPEN struct

Header File

windows.h

Syntax

typedef struct tagLOGPEN {

 UINT lopnStyle;

 POINT lopnWidth;

 COLORREF lopnColor;

} LOGPEN;

Description

Defines the style, width, and color of a pen.

Member	Description

lopnStyle	Specifies the pen type. This member can be one of the following values:

Value	Meaning

PS_SOLID	Solid pen

PS_DASH	Dashed pen (pen width = 1)

PS_DOT	Dotted pen (pen width = 1)

PS_DASHDOT	Alternating dashes and dots (pen width = 1)

PS_DASHDOTDOT	Alternating dashes and double dots
(pen width = 1)

PS_NULL	Invisible pen

PS_INSIDEFRAME	Creates a pen that draws a line inside the frame of closed shapes produced by graphics device interface (GDI) output functions that specify a bounding rectangle. When this style is used with GDI output functions.

lopnWidth	Specifies the pen width, in logical units. If the lopnWidth member is zero, the pen is one pixel wide on raster devices regardless of the current mapping mode.

lopnColor	Specifies the pen color.


MDICREATESTRUCT struct

Header File

typedef struct tagMDICREATESTRUCT {

 LPCSTR    szClass;

 LPCSTR    szTitle;

 HANDLE hOwner;

 int       x;

 int       y;

 int       cx;

 int       cy;

 DWORD     style;

 LPARAM    lParam;

} MDICREATESTRUCT;

Description

Contains class, title, location, owner, and size of a Multiple Document Interface (MDI) child window. The table below describes the members.

Member	Description

szClass	Points to a null-terminated string specifying the registered MDI child window name.

szTitle	Points to a null-terminated string specifying the registered MDI child window title.

hOwner	Instance handle for the application creating the MDI child window.

x	Initial position of the left side of the MDI child window. If set to CW_USEDEFAULT, the MDI child window is assigned a horizontal position.

y	Initial position of the MDI child window top edge. If set to CW_USEDEFAULT, the MDI child window is assigned a default vertical position.

cx	Initial width of the MDI child window. If set to CW_USEDEFAULT, the MDI child window is assigned a default width.

cy	Initial height of the MDI child window. If set to CW_USEDEFAULT, the MDI child window is assigned a default height.

style	Specifies additional styles for the MDI child window. If the MDI client window was created with the MDIS_ALLCHILDSTYLES window style, this member can be any combination of the window styles and creation attributes, including those listed in the following table:

Value	Meaning

WS_MINIMIZE	Created in a minimized state.

WS_MAXIMIZE	Created in a maximized state.

WS_HSCROLL	Created with a horizontal scroll bar.

WS_VSCROLL	Created with a vertical scroll bar.

lParam	An application-defined 32-bit value.


METARECORD struct

Header File

windows.h

Syntax

typedef struct tagMETARECORD {

 DWORD rdSize;

 WORD rdFunction;

 WORD rdParm[1];

} METARECORD;

Description

Contains a metafile record. The table below describes the members.

Member	Description

rdSize	Size of the record, in words.

rdFunction	Function number.

rdParm	Function parameters in reverse of the order they are passed to the function.


MEASUREITEMSTRUCT struct

Header File

windows.h

Syntax

typedef struct tagMEASUREITEMSTRUCT {

 UINT CtlType;

 UINT CtlID;

 UINT itemID;

 UINT itemWidth;

 UINT itemHeight;

 DWORD itemData;

} MEASUREITEMSTRUCT;

Description

Contains dimensions of an owner-drawn control. The table below describes the members.

Member	Description

CtlType	Specifies the control type and can be one of the following values:

ODT_BUTTON	Owner-drawn button

ODT_COMBOBOX	Owner-drawn combo box

ODT_LISTBOX	Owner-drawn list box

ODT_MENU	Owner-drawn menu

CtlID	Identifier of the combo box, list box, or button (not used for menus).

itemID	Menu item identifier for a menu item, or the list box item identifier for a variable-height list or combo box (not used for a fixed-height list box, combo box, or for a button).

itemWidth	Width of a menu item, in pixels.

itemHeight	Height of an individual item in a list box or a menu, in pixels.

itemData	Application-defined 32-bit value associated with a menu item. For a control, this parameter specifies the value last assigned to the list box or combo box by the LB_SETITEMDATA or CB_SETITEMDATA message. If the list box or combo box has the LB_HASSTRINGS or CB_HASSTRINGS style, this value is initially zero. Otherwise, this value is initially the value passed to the list box or combo box in the lParam parameter of one of the following messages:

CB_ADDSTRING

CB_INSERTSTRING

LB_ADDSTRING

LB_INSERTSTRING


MSG struct

Header File

windows.h

Syntax

typedef struct tagMSG {

 HWND hwnd;

 UINT message;

 WPARAM wParam;

 LPARAM lParam;

 DWORD time;

 POINT pt;

} MSG;

Description

The MSG structure contains the following message information from a message queue:

Member	Description

hwnd	Handle for the window whose window procedure receives the message.

message	Message number.

wParam	Additional message information. The meaning depends on the value of message.

lParam	Additional message information. The meaning depends on the value of message.

time	The time the message was posted.

pt	The cursor position when the message was posted, in screen coordinates.


OUTLINETEXTMETRIC struct

Header File

windows.h

Syntax

typedef struct _OUTLINETEXTMETRIC {

 UINT   otmSize;

 TEXTMETRIC otmTextMetrics;

 BYTE   otmFiller;

 PANOSE otmPanoseNumber;

 UINT   otmfsSelection;

 UINT   otmfsType;

 int    otmsCharSlopeRise;

 int    otmsCharSlopeRun;

 int    otmItalicAngle;

 UINT   otmEMSquare;

 int    otmAscent;

 int    otmDescent;

 UINT   otmLineGap;

 UINT   otmsCapEmHeight;

 UINT   otmsXHeight;

 RECT   otmrcFontBox;

 int    otmMacAscent;

 int    otmMacDescent;

 UINT   otmMacLineGap;

 UINT   otmusMinimumPPEM;

 POINT  otmptSubscriptSize;

 POINT  otmptSubscriptOffset;

 POINT  otmptSuperscriptSize;

 POINT  otmptSuperscriptOffset;

 UINT   otmsStrikeoutSize;

 int    otmsStrikeoutPosition;

 int    otmsUnderscoreSize;

 int    otmsUnderscorePosition;

 PSTR   otmpFamilyName;

 PSTR   otmpFaceName;

 PSTR   otmpStyleName;

 PSTR   otmpFullName;

} OUTLINETEXTMETRIC;

Description

Contains metrics describing a TrueType® font. The sizes returned in are given in logical units (depending on the specified display context's current mapping mode). The table below describes the members.

Member	Description

otmSize	Size of this structure, in bytes

otmTextMetrics	TEXTMETRIC structure containing additional font information

otmFiller	Value that causes this structure to be byte aligned

otmPanoseNumber	The PANOSE number for this font

otmfsSelection	Nature of the font pattern. Can be a combination of the following bits:

Bit	Meaning

0	Italic
1	Underscore
2	Negative
3	Outline
4	Strikeout
5	Bold

otmfsType	Specifies whether the font is licensed. Licensed fonts must not be modified or exchanged. If bit 1 is set, the font may not be embedded in a document. If bit 1 is clear, the font can be embedded. If bit 2 is set, the embedding is read-only.

otmsCharSlopeRise	Slope of the cursor. This value is 1 if the slope is vertical. Applications can use this value and the value of the otmsCharSlopeRun member to create an italic cursor that has the same slope as the main italic angle (specified by the otmItalicAngle member).

otmsCharSlopeRun	Slope of the cursor. This value is zero if the slope is vertical. Applications can use this value and the value of the otmsCharSlopeRise member to create an italic cursor that has the same slope as the main italic angle (specified by the otmItalicAngle member).

otmItalicAngle	Main italic angle of the font, in counterclockwise degrees from vertical. Regular (roman) fonts have a value of zero. Italic fonts typically have a negative italic angle (that is, they lean to the right).

otmEMSquare	Number of logical units defining the x- or y-dimension of the em square for this font. (The number of units in the x- and y-directions are always the same for an em square).

otmAscent	Maximum distance characters in this font extend above the base line. This is the typographic ascent for the font.

otmDescent	Maximum distance characters in this font extend below the base line. This is the typographic descent for the font.

otmLineGap	Typographic line spacing.

otmsCapEmHeight	Not supported.

otmsXHeight	Not supported.

otmrcFontBox	Bounding box for the font.

otmMacAscent	Maximum distance characters in this font extend above the base line for the Macintosh® computer.

otmMacDescent	Maximum distance characters in this font extend below the base line for the Macintosh® computer.

otmMacLineGap	Line-spacing information for the Macintosh® computer.

otmusMinimumPPEM	Specifies the smallest recommended size for this font in pixels per em-square.

otmptSubscriptSize	Recommended horizontal and vertical size for subscripts in this font.

otmptSubscriptOffset	Recommended horizontal and vertical offset for subscripts in this font. The subscript offset is measured from the character origin to the origin of the subscript character.

otmptSuperscriptSize	Recommended horizontal and vertical size for superscripts in this font.

otmptSuperscriptOffset	Recommended horizontal and vertical offset for superscripts in this font. The superscript offset is measured from the character base line to the base line of the superscript character.

otmsStrikeoutSize	Width of the strikeout stroke for this font. Typically, this is the width of the em-dash for the font.

otmsStrikeoutPosition	Position of the strikeout stroke relative to the base line for this font. Positive values are above the base line and negative values are below.

otmsUnderscoreSize	Thickness of the underscore character for this font.

otmsUnderscorePosition	Position of the underscore character for this font.

otmpFamilyName	Offset from the beginning of the structure to a string specifying the family name for the font.

otmpFaceName	Offset from the beginning of the structure to a string specifying the typeface name for the font. (This typeface name corresponds to the name specified in the LOGFONT structure.)

otmpStyleName	Offset from the beginning of the structure to a string specifying the style name for the font.

otmpFullName	Offset from the beginning of the structure to a string specifying the full name for the font. This name is unique for the font and often contains a version number or other identifying information.


RGBQUAD struct

Header File

windows.h

Syntax

typedef struct tagRGBQUAD {

 BYTE rgbBlue;

 BYTE rgbGreen;

 BYTE rgbRed;

 BYTE rgbReserved;

} RGBQUAD;

Description

Describes a color consisting of relative intensities of red, green, and blue. The following table  describes the members.

Member	Description

rgbBlue	Intensity of blue

rgbGreen	Intensity of green

rgbRed	Intensity of red

rgbReserved	Must be zero.


RGBTRIPLE struct

Header File

windows.h

Syntax

typedef struct tagRGBTRIPLE {

 BYTE rgbtBlue;

 BYTE rgbtGreen;

 BYTE rgbtRed;

} RGBTRIPLE;

Describes a color consisting of relative intensities of red, green, and blue.

Member	Description

rgbtBlue	Blue intensity

rgbtGreen	Green intensity

rgbtRed	Red intensity


TEXTMETRIC struct

Header File

windows.h

Syntax

The 16-bit version formatted and packed differently that the 32-bit version:

typedef struct tagTEXTMETRIC {

 int  tmHeight;

 int  tmAscent;

 int  tmDescent;

 int  tmInternalLeading;

 int  tmExternalLeading;

 int  tmAveCharWidth;

 int  tmMaxCharWidth;

 int  tmWeight;

 BYTE tmItalic;

 BYTE tmUnderlined;

 BYTE tmStruckOut;

 BYTE tmFirstChar;

 BYTE tmLastChar;

 BYTE tmDefaultChar;

 BYTE tmBreakChar;

 BYTE tmPitchAndFamily;

 BYTE tmCharSet;

 int  tmOverhang;

 int  tmDigitizedAspectX;

 int  tmDigitizedAspectY;

} TEXTMETRIC;

32-bit version:

typedef struct tagTEXTMETRIC {

 LONG tmHeight;

 LONG tmAscent;

 LONG tmDescent;

 LONG tmInternalLeading;

 LONG tmExternalLeading;

 LONG tmAveCharWidth;

 LONG tmMaxCharWidth;

 LONG tmWeight;

 LONG tmOverhang;

 LONG tmDigitizedAspectX;

 LONG tmDigitizedAspectY;

 BYTE tmFirstChar;

 BYTE tmLastChar;

 BYTE tmDefaultChar;

 BYTE tmBreakChar;

 BYTE tmItalic;

 BYTE tmUnderlined;

 BYTE tmStruckOut;

 BYTE tmPitchAndFamily;

 BYTE tmCharSet;

} TEXTMETRIC;

Description

Contains basic information about a physical font. All sizes are in logical units (mapping mode dependent). The table below describes the members.

Member	Description

tmHeight	Height of character cells. (tmAscent + tmDescent)

tmAscent	Ascent of character cells. (in units above base line)

tmDescent	Descent of character cells. (in units below base line)

tmInternalLeading	Amount of leading (space) inside the bounds set by tmHeight. Diacritical characters occur in this area

tmExternalLeading	Amount of extra leading (space) added between rows. Sometimes set to zero

tmAveCharWidth	Average width of characters in the font. Does not include overhang

tmMaxCharWidth	Width of the widest character in the font

tmWeight	Font weight. Can be one of the following values:

FW_DONTCARE	FW_SEMIBOLD

FW_THIN	FW_DEMIBOLD

FW_EXTRALIGHT	FW_BOLD

FW_ULTRALIGHT	FW_EXTRABOLD

FW_LIGHT	FW_ULTRABOLD

FW_NORMAL	FW_BLACK

FW_REGULAR	FW_HEAVY

FW_MEDIUM

tmItalic	Italic font if not 0

tmUnderlined	Underlined font if not 0

tmStruckOut	Struckout font if not 0

tmFirstChar	Value of first character defined in font

tmLastChar	Value of last character defined in font

tmDefaultChar	Value of non-font substitution character

tmBreakChar	Word-break character value for text justification.

tmPitchAndFamily	Pitch and family of the selected font. The four low-order bits identify the type of font, as follows:

TMPF_FIXED_PITCH	Fixed-pitch font.

TMPF_VECTOR	Vector or TrueType font.

TMPF_TRUETYPE	TrueType font.

TMPF_DEVICE	Device font.

The four high-order bits of this member designate the font family. The tmPitchAndFamily member can be combined with the hexadecimal value 0xF0 by using the bitwise AND operator and can then be compared with the font family names for an identical match. The following font families are defined:

Value	Meaning

FF_DECORATIVE	Novelty fonts

FF_DONTCARE	Don't care or don't know

FF_MODERN	Fonts with constant stroke width, with or without serifs

FF_ROMAN	Fonts with variable stroke width and with serifs

FF_SCRIPT	Fonts designed to look like handwriting

FF_SWISS	Fonts with variable stroke width and without serifs

tmCharSet	Specifies the character set of the font. The following values are defined:

ANSI_CHARSET

DEFAULT_CHARSET

SYMBOL_CHARSET

SHIFTJIS_CHARSET

OEM_CHARSET

tmOverhang	Extra width that is added to some synthesized fonts

tmDigitizedAspectX	Horizontal aspect of the device for which the font was designed. The ratio of tmDigitizedAspectX and tmDigitizedAspectY is the aspect ratio of the device for which the font was designed.

tmDigitizedAspectY	Specifies the vertical aspect of the device for which the font was designed. The ratio of tmDigitizedAspectX and tmDigitizedAspectY is the aspect ratio of the device for which the font was designed.


WNDCLASS struct

Header File

windows.h

Syntax

typedef struct tagWNDCLASS {

 UINT    style;

 WNDPROC lpfnWndProc;

 int     cbClsExtra;

 int     cbWndExtra;

 HANDLE  hInstance;

 HICON   hIcon;

 HCURSOR hCursor;

 HBRUSH  hbrBackground;

 LPCTSTR lpszMenuName;

 LPCTSTR lpszClassName;

} WNDCLASS;

Description

Contains twindow class registration attributes, described in the following table:

Member	Description

style	Class style. Can be any combination of the following values:

Value	Meaning

CS_BYTEALIGNCLIENT	Aligns the window's client area on the byte boundary (in the x direction).

CS_BYTEALIGNWINDOW	Aligns a window on a byte boundary (in the x direction) to enhance performance during operations that involve moving or sizing the window. This style affects the width of the window and its horizontal position on the display.

CS_CLASSDC	Allocates a device context (DC) to be shared by all windows in the class.

CS_DBLCLKS	Sends double-click messages to the window procedure while the cursor is within a window belonging to the class.

CS_GLOBALCLASS	Allows an application to create a window of the class regardless of the value of the hInstance parameter used at window creation.

lpfnWndProc	Points to the window procedure.

cbClsExtra	Number of extra bytes to allocate following the window-class structure. The operating system initializes the bytes to zero.

cbWndExtra	Number of extra bytes to allocate following the window instance. Initializedt to 0.

hInstance	Identifies the instance that the window procedure of this class is within.

hIcon	Identifies the class icon. Must be a handle of an icon resource. If NULL, an application must draw an icon whenever the user minimizes the application's window.

hCursor	Identifies the class cursor. Must be a handle of a cursor resource. If NULL, an application must set the cursor shape whenever the mouse moves into the application's window.

hbrBackground	Identifies the class background brush. Can be a handle to the physical brush to be used for painting the background, or it can be a color value. A color value must be one of the standard system colors listed below, plus 1. If a color value is given, you must convert it to one of the following HBRUSH types:

COLOR_ACTIVEBORDER	COLOR_HIGHLIGHTTEXT

COLOR_ACTIVECAPTION	COLOR_INACTIVEBORDER

COLOR_APPWORKSPACE	COLOR_INACTIVECAPTION

COLOR_BACKGROUND	COLOR_MENU

COLOR_BTNFACE	COLOR_MENUTEXT

COLOR_BTNSHADOW	COLOR_SCROLLBAR

COLOR_BTNTEXT	COLOR_WINDOW

COLOR_CAPTIONTEXT 	COLOR_WINDOWFRAME

COLOR_GRAYTEXT	COLOR_WINDOWTEXT

COLOR_HIGHLIGHT

An application should not delete these brushes, because a class may be used by multiple instances of an application.

When this member is NULL, an application must paint its own background whenever it is requested to paint in its client area.

lpszMenuName	Points to a null-terminated character string that specifies the resource name of the class menu, as the name appears in the resource file. If NULL, windows belonging to this class have no default menu.

lpszClassName	Points to a null-terminated string or is an atom that specifies the window class name.


PAINTSTRUCT struct

Header File

windows.h

16-bit version:

typedef struct tagPAINTSTRUCT {

 HDC  hdc;

 BOOL fErase;

 RECT rcPaint;

 BOOL fRestore;

 BOOL fIncUpdate;

 BYTE rgbReserved[16];

} PAINTSTRUCT;

32-bit version:

typedef struct tagPAINTSTRUCT {

 HDC  hdc;

 BOOL fErase;

 RECT rcPaint;

 BOOL fRestore;

 BOOL fIncUpdate;

 BYTE rgbReserved[32];

} PAINTSTRUCT;

Contains information needed by an application to paint the client area of a window.

Member	Description

hdc	The display device context used for painting.

fErase	If non-zero erase the background.

rcPaint	Specifies the upper-left and lower-right corners of the rectangle to be painted.

fRestore	Reserved

fIncUpdate	Reserved.

rgbReservedReserved.


PALETTEENTRY struct

Header File

windows.h

Syntax

typedef struct tagPALETTEENTRY {

 BYTE peRed;

 BYTE peGreen;

 BYTE peBlue;

 BYTE peFlags;

} PALETTEENTRY;

Description

Specifies the color and usage of an entry in a logical color palette (see LOGPALETTE struct). The following table describes the settings:

Member	Description

peRed	Specifies a red intensity value for the palette entry.

peGreen	Specifies a green intensity value for the palette entry.

peBlue	Specifies a blue intensity value for the palette entry.

peFlags	Specifies how the palette entry is to be used. The peFlags member may be set to NULL or one of these values:

Value	Meaning

PC_EXPLICIT	The low-order word of the logical palette entry designates a hardware palette index. This flag allows the application to show the contents of the display device palette.

PC_NOCOLLAPSE	The color is placed in an unused system palette entry instead of being matched to an existing system palette color.

PC_RESERVED	Specifies that the logical palette entry be used for palette animation, preventing other windows from matching colors to the palette entry since the color frequently changes. If an unused system-palette entry is available, this color is placed in that entry. Otherwise, the color is available for animation.


XFORM struct

Header File

windows.h

Syntax

typedef struct  tagXFORM {

 FLOAT eM11;

 FLOAT eM12;

 FLOAT eM21;

 FLOAT eM22;

 FLOAT eDx;

 FLOAT eDy;

} XFORM;

Syntax

Specifies a world-space to page-space transformation. The table below describes the members.

Member	Description

eM11	Specifies the following:

Value	Meaning

Scaling	Horizontal scaling component

Rotation	Cosine of rotation angle

Reflection	Horizontal component

eM12	Specifies the following:

Value	Meaning

Shear	Horizontal proportionality constant

Rotation	Sine of the rotation angle

eM21	Specifies the following:

Value	Meaning

Shear	Vertical proportionality constant

Rotation	Negative sine of the rotation angle

eM22	Specifies the following:

Value	Meaning

Scaling	Vertical scaling component

Rotation	Cosine of rotation angle

Reflection	Vertical reflection component

eDx	Specifies the horizontal translation component.

eDy	Specifies the vertical translation component.

The following table shows how the members are used for each operation:


Event Handlers (ObjectWindows)

See Also

These topics include several tables that list predefined ObjectWindows response-table macros and event-handling functions. Each table lists the name of the ObjectWindows macro, any required macro arguments, and the associated event-handling function. The tables are organized in the following manner:

Button Notification Messages

Child ID Notification Messages

Combo Box Notification Messages

Command Messages

Document Manager Messages

Document View Messages

Edit Control Notification Messages

List Box Notification Messages

ObjectComponents Messages

Scroll Bar Notification Messages

Standard Windows Messages

VBX Messages

User-defined Messages

Some event-handling functions or messages have no predefined names. In these cases, the generic term UserName is used to indicate that you can use any function name you want to as long as the function's signature matches the signature required by the response table macro. Similarly, the term UserMessage indicates that you can define your own message ID.

The descriptions of these macros and functions use the following conventions when listing the arguments of the message macros:

ID refers to the child window's ID (for example, ID_GROUPBOX)

CMD ID refers to the command ID (for example, CM_FILENEW)

Code refers to the notification code (for example, BN_CLICKED) that is being sent.


See Also

Event Handling Overview


Command Messages

OWL Event Handlers

These macros handle WM_COMMAND messages:

Macro	Macro Arguments	Response Function Declaration

EV_COMMAND	CMD ID, UserName	void UserName()

EV_COMMAND_AND_ID	CMD ID, UserName	void UserName(WPARAM)

EV_COMMAND_ENABLE	CMD ID, UserName	void UserName(TCommandEnabler&)


Standard Windows Messages

OWL Event Handlers

These macros handle Windows messages. These macros are defined in windowev.h. To determine the name of the Windows message that corresponds to the EV_XXXX macro, remove the EV_ prefix. For example, WM_ACTIVATE is the name of the Windows message that the EV_WM_ACTIVATE macro handles. These macros, which crack the standard Windows messages (break the LPARAM and WPARAM parameters into separate parts), take no arguments. They pass the cracked parameters directly to the predefined EVxxxx message function. The standard Windows messages are described in your Windows documentation.

Macro	Response Function Declaration

EV_WM_ACTIVATE	void EvActivate(uint active, bool minimized, HWND hWndOther)

EV_WM_ACTIVATEAPP	void EvActivateApp(bool active, HANDLE threadId) (WIN32 only)

EV_WM_ACTIVATEAPP	void EvActivateApp(bool active, HTASK hTask) (WIN16 only)

EV_WM_ASKCBFORMATNAME	void EvAskCBFormatName(uint bufLen, char far* buffer)

EV_WM_CANCELMODE	void EvCancelMode()

EV_WM_CHANGECBCHAIN	void EvChangeCBChain(uint bufLen, char far* buffer)

EV_WM_CHAR	void EvChar(uint key, uint repeatCount, uint flags)

EV_WM_CHARTOITEM	int EvCharToItem(uint key, HWND hWndListBox, uint caretPos)

EV_WM_CHILDACTIVATE	void EvChildActivate()

EV_WM_CHILDINVALID	void EvChildInvalid(HWND)

EV_WM_CLOSE	void EvClose()

EV_WM_COMPACTING	void EvCompacting(uint compactRatio)

EV_WM_COMPAREITEM	LRESULT EvCompareItem(uint ctrlId, COMPAREITEMSTRUCT far& compareInfo)

EV_WM_CREATE	int EvCreate(CREATESTRUCT far &)

EV_WM_CTLCOLOR	HBRUSH EvCtlColor(HDC, HWND hWndChild, uint ctlType)

EV_WM_DEADCHAR	void EvDeadChar(uint deadKey, uint repeatCount, uint flags)

EV_WM_DELETEITEM	void EvDeleteItem(uint ctrlId, DELETEITEMSTRUCT far& deleteInfo)

EV_WM_DESTROY	void EvDestroy()

EV_WM_DESTROYCLIPBOARD	void EvDestroyClipboard()

EV_WM_DEVMODECHANGE	void EvDevModeChange(char far* devMode)

EV_WM_DRAWCLIPBOARD	void EvDrawClipboard()

EV_WM_DRAWITEM	void EvDrawItem(uint ctrlId, DRAWITEMSTRUCT far& drawInfo)

EV_WM_DROPFILES	void EvDropFiles(TDropInfo dropInfo)

EV_WM_ENABLE	void EvEnable(bool enabled)

EV_WM_ENDSESSION	void EvEndSession(bool endSession)

EV_WM_ENTERIDLE	void EvEnterIdle(uint source, HWND hWndDlg)

EV_WM_ERASEBKGND	bool EvEraseBkgnd(HDC)

EV_WM_FONTCHANGE	void EvFontChange()

EV_WM_GETDLGCODE	uint EvGetDlgCode(MSG far*)

EV_WM_GETFONT	HFONT EvGetFont();

EV_WM_GETMINMAXINFO	void EvGetMinMaxInfo(MINMAXINFO far &)

EV_WM_GETTEXT	void EvGetText(uint bufLen, char far* buffer)

EV_WM_GETTEXTLENGTH	uint EvGetTextLength() (WIN32 only)

EV_WM_HOTKEY	void EvHotKey(int idHotKey)

EV_WM_HSCROLL	void EvHScroll(uint scrollCode, uint thumbPos, HWND hWndCtl)

EV_WM_HSCROLLCLIPBOARD	void EvHScrollClipboard(HWND hWndCBViewer, uint scrollCode, uint pos)

EV_WM_ICONERASEBKGND	void EvIconEraseBkgnd(HDC)

EV_WM_INITMENU	void EvInitMenu(HMENU)

EV_WM_INITMENUPOPUP	void EvInitMenuPopup(HMENU hPopupMenu, uint index, bool sysMenu)

EV_WM_INPUTFOCUS	void EvInputFocus(bool gainingFocus) (WIN32 only)

EV_WM_KEYDOWN	void EvKeyDown(uint key, uint repeatCount, uint flags)

EV_WM_KEYUP	void EvKeyUp(uint key, uint repeatCount, uint flags)

EV_WM_KILLFOCUS	void EvKillFocus(HWND hWndGetFocus)

EV_WM_LBUTTONDBLCLK	void EvLButtonDblClk(uint modKeys, TPoint& point)

EV_WM_LBUTTONDOWN	void EvLButtonDown(uint modKeys, TPoint& point)

EV_WM_LBUTTONUP	void EvLButtonUp(uint modKeys, TPoint& point)

EV_WM_MBUTTONDBLCLK	void EvMButtonDblClk(uint modKeys, TPoint& point)

EV_WM_MBUTTONDOWN	void EvMButtonDown(uint modKeys, TPoint& point)

EV_WM_MBUTTONUP	void EvMButtonUp(uint modKeys, TPoint& point)

EV_WM_MDIACTIVATE	void EvMDIActivate(HWND hWndActivated, HWND hWndDeactivated)

EV_WM_MDICREATE	LRESULT EvMDICreate(MDICREATESTRUCT far& createStruct)

EV_WM_MDIDESTROY	void EvMDIDestroy(HWND hWnd)

EV_WM_MENUCHAR	uint EvMenuChar(uint nChar, uint menuType, HMENU hMenu)

EV_WM_MENUSELECT	void EvMenuSelect(uint menuItemId, uint flags, HMENU hMenu)

EV_WM_MEASUREITEM	void EvMeasureItem(uint ctrlId, MEASUREITEMSTRUCT far& measureInfo)

EV_WM_MOUSEACTIVATE	uint EvMouseActivate(HWND hWndTopLevel, uint hitTestCode, uint msg)

EV_WM_MOUSEMOVE	void EvMouseMove(uint modKeys, TPoint& point)

EV_WM_MOVE	void EvMove(TPoint &clientOrigin)

EV_WM_NCACTIVATE	bool EvNCActivate(bool active)

EV_WM_NCCALCSIZE	uint EvNCCalcSize(bool calcValidRects, NCCALCSIZE_PARAMS far &)

EV_WM_NCCREATE	bool EvNCCreate(CREATESTRUCT far &)

EV_WM_NCDESTROY	void EvNCDestroy()

EV_WM_NCHITTEST	uint EvNCHitTest(TPoint& point)

EV_WM_NCLBUTTONDBLCLK	void EvNCLButtonDblClk(uint hitTest, TPoint& point)

EV_WM_NCLBUTTONDOWN	void EvNCLButtonDown(uint hitTest, TPoint& point)

EV_WM_NCLBUTTONUP	void EvNCLButtonUp(uint hitTest, TPoint& point)

EV_WM_NCMBUTTONDBLCLK	void EvNCMButtonDblClk(uint hitTest, TPoint& point)

EV_WM_NCMBUTTONDOWN	void EvNCMButtonDown(uint hitTest, TPoint& point)

EV_WM_NCMBUTTONUP	void EvNCMButtonUp(uint hitTest, TPoint& point)

EV_WM_NCMOUSEMOVE	void EvNCMouseMove(uint hitTest, TPoint& point)

EV_WM_NCPAINT	void EvNCPaint()

EV_WM_NCRBUTTONDBLCLK	void EvNCRButtonDblClk(uint hitTest, TPoint& point)

EV_WM_NCRBUTTONDOWN	void void EvNCRButtonDown(uint hitTest, TPoint& point)

EV_WM_NCRBUTTONUP	void EvNCRButtonUp(uint hitTest, TPoint& point)

EV_WM_OTHERWINDOWCREATED	void EvOtherWindowCreated(HWND hWndOther) (WIN32 only)

EV_WM_OTHERWINDOWDESTROYED	void EvOtherWindowDestroyed(HWND hWndOther) (WIN32 only)

EV_WM_PAINT	void EvPaint()

EV_WM_PAINTCLIPBOARD	void EvPaintClipboard(HWND, HANDLE hPaintStruct) (WIN32 only)

EV_WM_PAINTICON	void EvPaintIcon()

EV_WM_PALETTECHANGED	void EvPaletteChanged(HWND hWndPalChg)

EV_WM_PALETTEISCHANGING	void EvPaletteIsChanging(HWND hWndPalChg)

EV_WM_PARENTNOTIFY	void EvParentNotify(uint event, uint childHandleOrX, uint childIDOrY)

EV_WM_POWER	int EvPower(uint powerEvent)

EV_WM_QUERYDRAGICON	HANDLE EvQueryDragIcon()

EV_WM_QUERYENDSESSION	bool EvQueryEndSession()

EV_WM_QUERYNEWPALETTE	bool EvQueryNewPalette()

EV_WM_QUERYOPEN	bool EvQueryOpen()

EV_WM_RBUTTONDBLCLK	void EvRButtonDblClk(uint modKeys, TPoint& point)

EV_WM_RBUTTONDOWN	void EvRButtonDown(uint modKeys, TPoint& point)

EV_WM_RBUTTONUP	void EvRButtonUp(uint modKeys, TPoint& point)

EV_WM_RENDERALLFORMATS	void EvRenderAllFormats()

EV_WM_RENDERFORMAT	void EvRenderFormat(uint dataFormat)

EV_WM_SETCURSOR	bool EvSetCursor(HWND hWndCursor, uint hitTest, uint mouseMsg)

EV_WM_SETFOCUS	void EvSetFocus(HWND hWndLostFocus)

EV_WM_SETFONT	void EvSetFont(HFONT hFont, bool redraw)

EV_WM_SETTEXT	void EvSetText(char far* text)

EV_WM_SHOWWINDOW	void EvShowWindow(bool show, uint status)

EV_WM_SIZE	void EvSize(uint sizeType, TSize& size)

EV_WM_SIZECLIPBOARD	void EvSizeClipboard(HWND hWndViewer, HANDLE hRect)

EV_WM_SPOOLERSTATUS	void EvSpoolerStatus(uint jobStatus, uint jobsLeft)

EV_WM_SYSCHAR	void EvSysChar(uint key, uint repeatCount, uint flags)

EV_WM_SYSCOLORCHANGE	void EvSysColorChange()

EV_WM_SYSCOMMAND	void EvSysCommand(uint cmdType, TPoint& point)

EV_WM_SYSDEADCHAR	void EvSysDeadChar(uint key, uint repeatCount, uint flags)

EV_WM_SYSKEYDOWN	void EvSysKeyDown(uint key, uint repeatCount, uint flags)

EV_WM_SYSKEYUP	void EvSysKeyUp(uint key, uint repeatCount, uint flags)

EV_WM_SYSTEMERROR	void EvSystemError(uint error)

EV_WM_TIMECHANGE	void EvTimeChange()

EV_WM_TIMER	void EvTimer(uint timerId)

EV_WM_VKEYTOITEM	int EvVKeyToItem(uint key, HWND hWndListBox, uint caretPos)

EV_WM_VSCROLL	void EvVScroll(uint scrollCode, uint thumbPos, HWND hWndCtl)

EV_WM_VSCROLLCLIPBOARD	void EvVScrollClipboard(HWND hWndCBViewer, uint scrollCode, uint pos)

EV_WM_WINDOWPOSCHANGED	void EvWindowPosChanged(WINDOWPOS far &windowPos)

EV_WM_WINDOWPOSCHANGING	void EvWindowPosChanging(WINDOWPOS far &windowPos)

EV_WM_WININICHANGE	void EvWinIniChange(char far* section)


Child ID Notification Messages

OWL Event Handlers

The following macros handle messages that a child window sends to its parent:

Macro	Macro Arguments	Response Function Declaration

EV_CHILD_NOTIFY_AND_CODE	ID, Code, UserName	void UserName(WPARAM)

EV_CHILD_NOTIFY_ALL_CODES	ID, UserName	void UserName(UINT)

EV_NOTIFY_AT_CHILD	Code, UserName	void UserName

EV_CHILD_NOTIFY	ID, Code, UserName	void UserName


Button Notification Messages

OWL Event Handlers

These button macros handle BN_xxxx notification codes. To determine the name of the notification code that corresponds to the EV_XXXX macro, remove the EV_ prefix.

Macro	Macro Arguments	Response Function Declaration

EV_BN_CLICKED	ID, UserName	void UserName()

EV_BN_DISABLE	ID, UserName	void UserName()

EV_BN_DOUBLECLICKED 	D, UserName	void UserName()

EV_BN_HILITE	ID, UserName	void UserName()

EV_BN_PAINT	ID, UserName	void UserName()

EV_BN_UNHILITE	ID, UserName	void UserName()


Combo Box Notification Messages

OWL Event Handlers

These combo box macros handle CBN_xxxx notification codes. To determine the name of the notification code that corresponds to the EV_XXXX macro, remove the EV_ prefix.

Macro	Macro Arguments	Response Function Declaration

EV_CBN_CLOSEUP	ID, UserName	void UserName()

EV_CBN_DBLCLK	ID, UserName	void UserName()

EV_CBN_DROPDOWN	ID, UserName	void UserName()

EV_CBN_EDITCHANGE	ID, UserName	void UserName()

EV_CBN_EDITUPDATE	ID, UserName	void UserName()

EV_CBN_ERRSPACE	ID, UserName	void UserName()

EV_CBN_KILLFOCUS	ID, UserName	void UserName()

EV_CBN_SELCHANGE	ID, UserName	void UserName()

EV_CBN_SELENDCANCEL	ID, UserName	void UserName()

EV_CBN_SELENDOK	ID, UserName	void UserName()

EV_CBN_SETFOCUS	ID, UserName	void UserName()


List Box Notification Messages

OWL Event Handlers

These list box macros handle LBN_xxxx notification codes. To determine the name of the notification code that corresponds to the EV_XXXX macro, remove the EV_ prefix.

Macro	Macro Arguments	Response Function Declaration

EV_LBN_DBLCLK	ID, UserName	void UserName()

EV_LBN_ERRSPACE	ID, UserName	void UserName()

EV_LBN_KILLFOCUS	ID, UserName	void UserName()

EV_LBN_SELCANCEL	ID, UserName	void UserName()

EV_LBN_SELCHANGE	ID, UserName	void UserName()

EV_LBN_SETFOCUS	ID, UserName	void UserName()


Edit Control Notification Messages

OWL Event Handlers

These edit control macros handle EN_xxxx notification codes. To determine the name of the notification code that corresponds to the EV_XXXX macro, remove the EV_ prefix.

Macro	Macro Arguments	Response Function Declaration

EV_EN_CHANGE	ID, UserName	void UserName()

EV_EN_ERRSPACE	ID, UserName	void UserName()

EV_EN_HSCROLL	ID, UserName	void UserName()

EV_EN_KILLFOCUS	ID, UserName	void UserName()

EV_EN_MAXTEXT	ID, UserName	void UserName()

EV_EN_SETFOCUS	ID, UserName	void UserName()

EV_EN_UPDATE	ID, UserName	void UserName()

EV_EN_VSCROLL	ID, UserName	void UserName()


Document Manager Messages

OWL Event Handlers

These macros handle messages generated by the document manager:

Macro	Macro Arguments	Response Function Declaration

EV_OWLDOCUMENT	ID, UserName	void UserName(TDocument& document)

EV_OWLNOTIFY	ID, UserName	bool UserName(LPARAM&)

EV_OWLVIEW	ID, UserName	void UserName(TView& view)


Document View Messages

OWL Event Handlers

These macros handle view-related messages generated by the document manager. VnHandler is a generic term for the view notification handler function.

Macro	Response Function Declaration

EV_VN_COMMIT	bool VnCommit(bool force)

EV_VN_DOCCLOSED	bool VnDocClosed(int openMode)

EV_VN_DOCOPENED	bool VnDocOpened(int openMode)

EV_VN_ISDIRTY	bool VnIsDirty()

EV_VN_ISWINDOW	bool VnIsWindow(HWND hWnd)

EV_VN_VIEWCLOSED	bool VnViewClosed(TView* view)

EV_VN_VIEWOPENED	bool VnViewOpened(TView* view)

EV_VN_REVERT	bool VnRevert(bool clear)


VBX Messages

OWL Event Handlers

The following macros handle WM_VBXFIREEVENT messages generated by VBX controls. EvHandler is a generic term for a specific VBX control message (such as EvClick).

Macro	Macro Arguments	Response Function Declaration

EV_VBXEVENTINDEX	ID, event, EvHandler	void EvHandler(VBXEVENT FAR *event)

EV_VBXEVENTNAME	ID, event, EvHandler	void EvHandler(VBXEVENT FAR *event)


Scroll Bar Notification Messages

OWL Event Handlers

The following scrollbar control macros handle SB_xxxx notification codes. To determine the name of the notification code that corresponds to the EV_XXXX macro, remove the EV_ prefix.

Macro	Macro Arguments	Response Function Declaration

EV_SB_BEGINTRACK	ID, UserName	void UserName()

EV_SB_BOTTOM	ID, UserName	void UserName()

EV_SB_ENDSCROLL	ID, UserName	void UserName()

EV_SB_LINEDOWN	ID, UserName	void UserName()

EV_SB_LINEUP	ID, UserName	void UserName()

EV_SB_PAGEDOWN	ID UserName	void UserName()

EV_SB_PAGEUP	ID, UserName	void UserName()

EV_SB_THUMBPOSITION	ID, UserName	void UserName()

EV_SB_TOP	ID, UserName	void UserName()


ObjectComponents Messages

OWL Event Handlers

The following macros handle ObjectComponents messages:

Macro	Response Function Declaration

EV_OC_APPBORDERSPACEREQ	bool EvOcAppBorderSpaceReq(TRect far* rect)

EV_OC_APPBORDERSPACESET	bool EvOcAppBorderSpaceSet(TRect far* rect)

EV_OC_APPDIALOGHELP	void EvOcAppDialogHelp(TOcDialogHelp far& dh)

EV_OC_APPFRAMERECT	bool EvOcAppFrameRect(TRect far* rect)

EV_OC_APPINSMENUS	bool EvOcAppInsMenus(TOcMenuDescr far&)

EV_OC_APPMENUS	bool EvOcAppMenus(TOcMenuDescr far& md)

EV_OC_APPPROCESSMSG	bool EvOcAppProcessMsg(MSG far* msg)

EV_OC_APPRESTOREUI	void EvOcAppRestoreUI()

EV_OC_APPSHUTDOWN	void EvOcAppShutDown()

EV_OC_APPSTATUSTEXT	void EvOcAppStatusText(const char far* rect)

EV_OC_VIEWATTACHWINDOW	bool EvOcViewAttachWindow()

EV_OC_VIEWBORDERSPACEREQ	bool EvOcViewBorderSpaceReq(TRect far* rect)

EV_OC_VIEWBORDERSPACESET	bool EvOcViewBorderSpaceSet(TRect far& rect)

EV_OC_BREAKLINK	bool EvOcViewBreakLink(TOcLinkView& view)

EV_OC_VIEWCLIPDATA	HANDLE EvOcViewClipData(TOcFormat far& format)

EV_OC_VIEWCLOSE	bool EvOcViewClose()

EV_OC_VIEWDRAG	bool EvOcViewDrag(TOcDragDrop far& ddInfo)

EV_OC_VIEWDROP	bool EvOcViewDrop(TOcDragDrop far& ddInfo)

EV_OC_VIEWGETPALETTE	bool EvOcViewGetPalette(LOGPALETTE far* far*)

EV_OC_VIEWGETSCALE	bool EvOcViewGetScale(TOcScaleFactor&)

EV_OC_VIEWGETSITERECT	bool EvOcViewGetSiteRect(TRect far* rect)

EV_OC_VIEWINSMENUS	bool EvOcViewInsMenus(TOcMenuDescr far&)

EV_OC_VIEWLOADPART	bool EvOcViewLoadPart(TOcSaveLoad far& ocLoad)

EV_OC_VIEWOPENDOC	bool EvOcViewOpenDoc(const char far* path)

EV_OC_VIEWPAINT	bool EvOcViewPaint(TOcViewPaint far& vp)

EV_OC_VIEWPARTACTIVATE	bool EvOcViewPartActivate(TOcPart& ocPart)

EV_OC_VIEWPARTINVALID	bool EvOcViewPartInvalid(TOcPart far& part)

EV_OC_VIEWPARTSIZE	bool EvOcViewPartSize(TRect far* size)

EV_OC_VIEWSAVEPART	bool EvOcViewSavePart(TOcSaveLoad far& ocSave)

EV_OC_VIEWSCROLL	bool EvOcViewScroll (TOcScrollDir scrollDir)

EV_OC_SETLINK	bool EvOcViewSetLink(TOcLinkView& view)

EV_OC_VIEWSETSCALE	bool EvOcViewSetScale(TOcScaleFactor&)

EV_OC_VIEWSETSITERECT	bool EvOcViewSetSiteRect(TRect far* rect)

EV_OC_VIEWSHOWTOOLS	bool EvOcViewShowTools(TOcToolBarInfo far& tbi)

EV_OC_VIEWTITLE	const char far* EvOcViewTitle()


User-defined Messages

OWL Event Handlers

The following macros handle user-defined messages:

Macro	Macro Arguments	Response Function Declaration

EV_MESSAGE	UserMessage, UserName	LRESULT UserName(WPARAM,LPARAM)

EV_REGISTERED	Registered name, UserName	LRESULT UserName(WPARAM,LPARAM)


Object Windows Dispatch Functions

See Also	List of Object Windows Dispatch Functions

Dispatch functions separate the lParam and wParam parameters of Windows messages into their respective data types and pass control to an ObjectWindows member function.

For example, when Windows sends an application a WM_CTLCOLOR message, the wParam is really an HDC, and the lParam has a HWND and a uint hidden inside. After the dispatch function cracks the wParam and lParam parameters into their constituent parts, it dispatches the Windows WM_CTLCOLOR message to the following ObjectWindows member function:

HBRUSH EvCtlColor(HDC, HWND, uint);

Although dispatch functions are written for specific Windows API messages, they have no knowledge of the actual Windows messages they are cracking. Instead, at run time, TEventHandler::Dispatch calls the appropriate dispatch function which then cracks the message and calls the appropriate member function, using the response table's pmf (pointer to a member function). These dispatch functions are never called directly.

The following four parameters are common to all dispatch functions.

GENERIC& generic is the pointer to the object (for example, TEdit).

GENERIC::*pmf is the pointer to the member function (for example, EvActivate).

WPARAM is one of the message parameters the dispatch function cracks.

LPARAM is one of the message parameters the dispatch function cracks.

The name of the dispatch function used in the response table entry or macro depends on the type of message cracking the function performs. The first letter of the name indicates the return type (for example, U indicates an unsigned integer). The second group of letters signifies the arguments of the function (for example, POINT of type TPOINT, or U of type uint). The following table lists the abbreviations of the member functions' signatures and their corresponding data types.

Abbreviation	Data type

i	int

v	void

H	HANDLE (same as uint in size)

I32	int32

POINT	TPoint& (TPoint object constructed)

POINTER	void* (model's ambient size)

U	uint

Message crackers that serve customized messages have names based on the specific message they crack. For example, the message cracker for WM_MDIACTIVATE messages has the following prototype:

int32_v_MdiActivate_Dispatch(GENERIC& generic, HBRUSH (GENERIC::*pmf)(uint, uint), uint  wParam, int32 lParam);

ObjectWindows uses the same dispatch functions for messages that require the same type of cracking. For example, both the WM_HSCROLL and WM_VSCROLL event handlers have void (*)( uint, uint, HWND) as their signature. The Windows message also has the wParam and lParam parameters in the same place. Therefore, ObjectWindows uses the same dispatch functions for both of these messages.

The following aliases have been defined for purposes of backward compatibility:

#define HBRUSH_HDC_W_U_Dispatch          U_U_U_U_Dispatch

#define LRESULT_U_U_W_Dispatch           I32_MenuChar_Dispatch

#define LRESULT_WPARAM_LPARAM_Dispatch   I32_WPARAM_LPARAM_Dispatch

#define v_U_B_W_Dispatch                 v_Activate_Dispatch

#define v_W_W_Dispatch                   v_MdiActivate_Dispatch


See Also

TEventHandler


List of Object Windows Dispatch Functions

i_LPARAM_Dispatch

i_U_W_U_Dispatch

i_WPARAM_Dispatch

I32__Dispatch

I32_LPARAM_Dispatch

I32_WPARAM_LPARAM_Dispatch

I32_MenuChar_Dispatch

I32_U_Dispatch

U_Dispatch

U_LPARAM_Dispatch

U_POINT_Dispatch

U_POINTER_Dispatch

U_U_Dispatch

U_U_U_U_Dispatch

U_WPARAM_LPARAM_Dispatch

v_Activate_Dispatch

v_Dispatch

v_LPARAM_Dispatch

v_MdiActivate_Dispatch

v_ParentNotify_Dispatch

v_POINT_Dispatch

v_POINTER_Dispatch

v_U_Dispatch

v_U_POINT_Dispatch

v_U_U_Dispatch

v_U_U_U_Dispatch

v_U_U_W_Dispatch

v_WPARAM_Dispatch

v_WPARAM_LPARAM_Dispatch


i_LPARAM_Dispatch

Syntax

int32 i_LPARAM_Dispatch(GENERIC& generic, int (GENERIC::*pmf)(int32), uint  wParam, int32 lParam);

Header File

Dispatch.h

Description

Passes lParam as an int32 and returns an int.


i_U_W_U_Dispatch

Syntax

int32 i_U_W_U_Dispatch(GENERIC& generic, int (GENERIC::*pmf)(uint, uint, uint), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

For Win 32, passes wParam.lo (the LOWORD of wParam) as a uint, lParam as a uint and wParam.hi (the HIWORD of wParam) as a uint and returns an int. For Win 16, passes wParam as a uint, lParam.lo as a uint and lParam.hi as a uint and returns an int. This is a semi-customized dispatch function used for WM_CHARTOITEM and WM_KEYTOITEM messages.


i_WPARAM_Dispatch

Syntax

int32 i_WPARAM_Dispatch(GENERIC& generic, int (GENERIC::*pmf)(uint), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Passes wParam  as a uint and returns an int.


I32_Dispatch

Syntax

int32 I32_Dispatch(GENERIC& generic, int32 (GENERIC::*pmf)(), uint, int32);

Header File

Dispatch.h

Description

This dispatcher passes nothing and returns an int32.


I32_LPARAM_Dispatch

Syntax

int32 I32_LPARAM_Dispatch(GENERIC& generic, int32 (GENERIC::*pmf)(int32), uint, int32 lParam);

Header File

Dispatch.h

Description

This dispatcher passes lParam as an int32 and returns an int32.


MenuChar_Dispatch
I32_MenuChar_Dispatch

Syntax

int32 I32_MenuChar_Dispatch(GENERIC& generic, uint (GENERIC::*pmf) (uint, uint, uint), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Cracker for WM_PARENTNOTIFY messages. Passes three uints and returns an int32. Under Win32, the first uint is wParam.lo, the second uint is wParam,hi, and the uint is lParam. Under Win 16, the first uint is wParam, the second uint is lParam.lo, and the third uint is lParam.hi.


I32_U_Dispatch

Syntax

int32 I32_U_Dispatch(GENERIC& generic, int32 (GENERIC::*pmf)(uint), int32 lParam);

Header File

Dispatch.h

Description

This dispatcher passes lParam and uint and returns an int32.


I32_WPARAM_LPARAM_Dispatch

Syntax

int32 I32_WPARAM_LPARAM_Dispatch(GENERIC& generic, int32 (GENERIC::*pmf)(uint, int32), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

This dispatcher passes wParam as  a uint and lParam as an int32., and returns an int32.


U_Dispatch

Syntax

int32 U_Dispatch(GENERIC& generic, uint (GENERIC::*pmf) (), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Passes no arguments and returns a uint.


U_LPARAM_Dispatch

Syntax

int32 U_LPARAM_Dispatch(GENERIC& generic, uint (GENERIC::*pmf) (int32), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

passes lParam as an int32 and returns a uint.


U_POINT_Dispatch

Syntax

int32 U_POINT_Dispatch(GENERIC& generic, uint (GENERIC::*pmf) (TPoint&), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Passes lParam as a TPoint& and returns a uint.


U_POINTER_Dispatch

Syntax

int32 U_POINTER_Dispatch(GENERIC& generic, uint (GENERIC::*pmf) (void*), uint, int32 lParam);

Header File

Dispatch.h

Description

Passes lParam as a void* and returns a uint.


U_U_Dispatch

Syntax

int32 U_U_Dispatch(GENERIC& generic, uint (GENERIC::*pmf) (uint), uint, int32 lParam);

Header File

Dispatch.h

Description

Passes lParam as a uint and returns a uint.


U_U_U_U_Dispatch

Syntax

int32 U_U_U_U_Dispatch(GENERIC& generic, uint (GENERIC::*pmf) (uint, uint, uint), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Passes three uints and returns a uint. The first uint is wParam, the second uint is the LOWORD of lParam, and the third uint is the HIWORD of lParam.


v_ParentNotify_Dispatch

Syntax

int32 v_ParentNotify_Dispatch(GENERIC& generic, int(GENERIC::*pmf) (uint, uint, uint), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Performs message cracking for WM_PARENTNOTIFY messages, which notify a parent window that a given event has occurred in the child window. Passes three uints and always returns 0. For Win16,  the first uint is wParam, the second uint is lParam.lo, and the third uint is lParam.hi. For Win32, if wparam.lo is a mouse message, then the first uint is wparam, the second uint is lparam.lo, and the third uint is lParam.hi. Otherwise, the first uint is wparam.lo, the second uint is lParam, and the third uint is wParam.hi


U_WPARAM_LPARAM_Dispatch

Syntax

int32 U_WPARAM_LPARAM_Dispatch(GENERIC& generic, uint (GENERIC::*pmf) (uint, int32), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Passes wParam as a uint and lParam as an int32 and returns a uint.


v_Activate_Dispatch

Syntax

int32 v_Activate_Dispatch(GENERIC& generic, void (GENERIC::*pmf) (uint, uint, uint), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Cracker for WM_ACTIVATE messages. Passes three uints and always returns 0. Under Win32, the first uint is  wParam.lo, the second uint is wParam.hi, and the third uint is lParam. Under Win16, the first uint is wParam, the second  uint is  lParam.hi, and the third uint is lParam.lo.


v_Dispatch

Syntax

int32 v_Dispatch (GENERIC& generic, void (GENERIC::*pmf) (), uint uint, int32);

Header File

Dispatch.h

Description

Passes nothing and always returns 0.


v_LPARAM_Dispatch

Syntax

int32 v_LPARAM_Dispatch (GENERIC& generic, void (GENERIC::*pmf) (int32), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Passes lParam as an int32 and always returns 0.


v_MdiActivate_Dispatch

Syntax

int32 v_MdiActivate_Dispatch(GENERIC& generic, void (GENERIC::*pmf)(uint, uint), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Specifically designed to handle EvMDIActivate messages, v_MdiActivate_Dispatch passes two uints and always returns 0. Under Win32, the first uint is lParam and the second uint is wParam. Under Win16, the first uint is lParam.lo. If lParam is nonzero, the second uint is lParam.hi; otherwise, the second uint is wParam.


v_POINT_Dispatch

Syntax

int32 v_POINT_Dispatch (GENERIC& generic, void (GENERIC::*pmf) (TPoint&), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Passes a reference to a POINT (TPoint&)  and always returns 0. Under Win32, passes lParam; under Win16, passes a reference to lParam.


v_POINTER_Dispatch

Syntax

int32 v_POINTER_Dispatch(GENERIC& generic, void (GENERIC::*pmf)(void*), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Passes an lParam as a void*pointer and always returns 0.


v_U_Dispatch

Syntax

int32 v_U_Dispatch(GENERIC& generic, void (GENERIC::*pmf) (uint, int32 lParam);

Header File

Dispatch.h

Description

Passes lParam as a uintand always returns 0.


v_U_POINT_Dispatch

Syntax

int32 v_U_POINT_Dispatch(GENERIC& generic, void (GENERIC::*pmf) (uint, TPoint&), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Passes wparam as a uint and lParam as a reference to a POINT and always returns 0.


v_U_U_Dispatch

Syntax

int32 v_U_U_Dispatch(GENERIC& generic, void (GENERIC::*pmf) (uint, uint), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Passes two uint and always returns 0. The first uint is wParam and the second uint is lParam.


v_U_U_U_Dispatch

Syntax

int32 v_U_U_U_Dispatch(GENERIC& generic, void (GENERIC::*pmf) (uint, uint, uint), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Passes three uints and always returns 0. The first uint is wParam, the second uint is lParam.lo and the third uint is lParam.hi.


v_U_U_W_Dispatch

Syntax

int32 v_U_U_W_Dispatch(GENERIC& generic, void (GENERIC::*pmf) (uint, uint, uint), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Passes three uintsand always returns 0. Under Win32, the first uint is  wParam.lo., the second uint is wParam.hi, and the third uintis lParam Under Win16, the first uint is wParam, the second uint is lParam.lo, and the third uint is lParam.hi. This is a semi-customized message cracker for WM_HSCROLL, WM_VSCROLL, and WM_MENUSELECT messages.


v_WPARAM_Dispatch

Syntax

int32 v_WPARAM_Dispatch(GENERIC& generic, void (GENERIC::*pmf) (uint), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Passes wParam as a uint and always returns 0.


v_WPARAM_LPARAM_Dispatch

Syntax

int32 v_WPARAM_LPARAM_Dispatch(GENERIC& generic, void (GENERIC::*pmf) (uint, int32), uint wParam, int32 lParam);

Header File

Dispatch.h

Description

Passes wParam as a uint and lParam as an int32 and always returns 0.


Application and Modlue Objects Overview (ObjectWindows)
Application and Module Objects Overview (ObjectWindows)

See Also

ObjectWindows encapsulates Windows applications and DLL modules using the TApplication and TModule classes, respectively.

TModule

TModule objects encapsulate the initialization and closing functions of a Windows DLL. The TModule object also contains the hInstance and lpCmdLine parameters, which are equivalent to the parameters of the same name that are passed to the WinMain function in a non-ObjectWindows application. Note that both WinMain and LibMain have these two parameters in common.

Unless you're working with a DLL, you do not need to create a TModule object yourself.

TApplication

To use a TApplication object, you must

1.	Include the right header file

2.	Create an application object

3.	Call the Run function

TApplication objects encapsulate the initialization, run-time management, and closing functions of a Windows application. A TApplication object also contains the values of the hPrevInstance and nCmdShow parameters, which are equivalent to the parameters of the same name that are passed to the WinMain function in a non-ObjectWindows application. And because TApplication is based on TModule, it also has all the functionality contained in TModule.

You might need to access an application object from outside that object's scope . For example, you might need to call one of the object's member functions from a function in a derived window class. But because the window object is not in the same scope as the application object, you have no way of accessing the application object. In this case, you must find the application object.

In addition, the TApplication object contains functions to easily load and use the Borland Custom Controls Library and the Microsoft 3-D Controls Library. There is also a function that automatically subclasses standard controls as Microsoft 3-D controls.

You don't have to provide an explicit WinMain function for your ObjectWindows applications; you can instead use the function OwlMain. OwlMain lets you use int argc and char** argv parameters and return an int, just like a traditional C or C++ program with a main function.


See Also

Creating an Object (ObjectWindows)

Finding the Object (ObjectWindows)

Creating a Minimum Application (ObjectWindows)

Initializing Applications (ObjectWindows)

Closing Applications (ObjectWindows)

Application Message Handling

Using Control Libraries (ObjectWindows)


Including the Header File (ObjectWindows)

TApplication is defined in the header file owl\applicat.h. You must include this header file to use TApplication. Because TApplication is derived from TModule, owl\applicat.h includes owl\module.h.


Creating an Object (ObjectWindows)

You can create a TApplication object using one of two constructors. The most commonly used constructor is this:

TApplication(const char far* name);

This version of the TApplication constructor takes a string, which becomes the application's name. If you don't specify a name, by default the constructor names it the null string. TApplication uses this string as the application name.

The second version of the TApplication constructor lets you specify a number of parameters corresponding to the parameters normally passed to the WinMain function:

TApplication(const char far* name,

             HINSTANCE instance,

             HINSTANCE prevInstance,

             const char far* cmdLine,

             int cmdShow){}

You can use this constructor to pass command parameters to the TApplication object.


Calling the Run Function (ObjectWindows)

The most obvious thing that the TApplication::Run function does is to start your application running. But in doing so it performs a number of other important tasks, including

 	Initializing the application

 	Creating and displaying the main window

 	Running the application's message loop

For the purposes of creating the basic application, it is sufficient to know that Run is the function you call to make your application go.


Finding the Object (ObjectWindows)

You might need to access an application object from outside that object's scope . For example, you might need to call one of the application object's member functions from a function in a derived window class, but because the window object is not in the same scope as the application object, you have no way of accessing the application object. In this case, you must find the application object.

To find the current application object from a window object, TWindow has a member function, GetApplication, that returns a pointer to the application object. You can use this pointer to call TApplication member functions and access TApplication data members. The following listing shows a possible use of GetApplication:

void TMyWindow::Error()

{

  // display message box containing the application name

  MessageBox("An error occurred!",

             GetApplication()->Name, MB_OK);

}


Creating a Minimum Application
Creating a Minimum Application (ObjectWindows)

Here's the smallest application you can create. It includes the correct header file, creates a TApplication object, and calls that object's Run function.

#include <owl\applicat.h>

int OwlMain(int argc, char* argv[])

{

  return TApplication("Wow!").Run();

}

This example creates a Windows application having a main window with the caption "Wow!" You can resize, move, minimize, maximize, and close this window. In a real application, you would derive a new class for the application to add more functionality. Notice that the only function you have to call explicitly in this example is the Run function.


Initializing Applications (ObjectWindows)

See Also

Initializing an ObjectWindows application takes four steps:

Constructing the application object

Initializing the application

Initializing each new instance

Initializing the main window


See Also

Application Message Handling (ObjectWindows)

Application Objects Overview (ObjectWindows)

Closing Applications (ObjectWindows)

Using Control Libraries (ObjectWindows)


Constructing the Application Object (ObjectWindows)

When you construct a TApplication object, it calls its InitApplication, InitInstance, and InitMainWindow member functions to start the application. You can override any of those members to customize how your application initializes. You must override InitMainWindow to have a useful application. To override a function in TApplication you need to derive your own application class from TApplication.

The constructor for the TApplication-derived class TMyApplication, shown in the examples that follow, takes the application name as its only argument; its default value is zero, for no name. The application name is used for the default main window title and in error messages. The application name is referenced by a char far* member of the TModule base class called Name. You can set the application name one of two ways:

Your application class constructor can explicitly call TApplication's constructor, passing the application name onto TApplication. The following example shows this method:

#include <owl\applicat.h>

class TMyApplication: public TApplication

{

  public:

    // This constructor initializes the base class constructor

    TMyApplication(const char far* name = 0) : TApplication(name) {}

    .

    .

    .

};

Override one of TApplication's initialization functions, usually InitMainWindow, and set the application name there. The following example shows this method:

#include <owl\applicat.h>

class TMyApplication: public TApplication

{

  public:

    // This constructor just uses the default base class constructor.

    TMyApplication(const char far* name = 0) : Name(name) {}

    void InitMainWindow()

 {

  .

  .

  .

protected:

  string Name;

};

ObjectWindows applications do not require an explicit WinMain function; the ObjectWindows libraries provide one that performs error handling and exception handling. You can perform any initialization you want in the OwlMain function, which is called by the default WinMain function.

To construct an application object, create an instance of your application class in the OwlMain function. The following example shows a simple application object's definition and instantiation:

#include <owl\applicat.h>

class TMyApplication: public TApplication

{

public:

  TMyApplication(const char far* name = 0): TApplication(name) {}

};

int OwlMain(int argc, char* argv[])

{

  return TMyApplication("Wow!").Run();

}


Using WinMain and OwlMain (ObjectWindows)

ObjectWindows provides a default WinMain function that provides extensive error checking and exception handling. This WinMain function sets up the application and calls the OwlMain function.

Although you can use your own WinMain by placing it in a source file, there is little reason to do so. Everything you would otherwise do in WinMain you can do in OwlMain or in TApplication initialization member functions. In the following example, OwlMain checks to see whether the use specified any parameters on the application's command line. If so, OwlMain creates the application object and uses the first parameter as the application name. If not, OwlMain creates the application object and uses Wow! as the application name.

#include <owl\applicat.h>

#include <string.h>

class TMyApplication: public TApplication

{

public:

  TMyApplication(const char far* name = 0) : TApplication(name) {}

};

int

OwlMain(int argc, char* argv[])

{

  char title[30];

  if(argc >= 2)

    strcpy(title, argv[1]);

  else

    strcpy(title, "Wow!");

  return TMyApplication(title).Run();

}

If you do decide to provide your own WinMain, TApplication supports passing traditional WinMain function parameters with another constructor. The following example shows how to use that constructor to pass WinMain parameters to the TApplication object:

#include <owl\applicat.h>

class TMyApplication : public TApplication

{

public:

  TMyApplication (const char far* name,

                  HINSTANCE       instance,

                  HINSTANCE       prevInstance,

                  const char far* cmdLine,

                  int             cmdShow)

    : TApplication (name, instance, prevInstance, cmdLine, cmdShow){}

};

int

PASCAL WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,

               LPSTR lpszCmdLine, int nCmdShow)

{

  return TMyApplication("MyApp", hInstance, hPrevInstance,

                        lpszCmdLine, nCmdShow).Run();

}


Initializing the Application (ObjectWindows)

See Also

TApplication contains three initialization functions:

{bmc bullet.bmp)	InitApplication initializes the first instance of the application.

{bmc bullet.bmp)	InitInstance initializes each instance of the application.

{bmc bullet.bmp)	InitMainWindow initializes the application's main window.

How these functions are called depends on whether this is the first instance of the application. For 16-bit applications, InitApplication is called only for the first instance of the application on the system. InitInstance is the next function called for the first instance, and it is the first function called by additional instances. InitInstance calls InitMainWindow.

In the case of 32-bit applications, each application runs in its own address space, with no shared instance data, making each instance a first instance. Therefore every time you start a 32-bit application, it performs both first-instance initialization and each-instance initialization.

If the current instance is a first instance (indicated by the data member hPrevInstance being set to zero), InitApplication is called. You can override InitApplication in your derived application class; the default InitApplication has no functionality.

For example, you could use first-instance initialization to make the main window's caption indicate whether it's the first instance. To do this, add a data member called WindowTitle in your derived application class. In the constructor, set WindowTitle to "Additional Instance". Then override InitApplication to set WindowTitle to "First Instance". If your application is the first instance of the application, InitApplication is called and overwrites what the constructor set WindowTitle to. The following example shows how the code might look:

#include <owl\applicat.h>

#include <owl\framewin.h>

#include <cstring.h>

class TTestApp : public TApplication

{

  public:

    TTestApp() : TApplication(Instance Tester),

                 WindowTitle(Additional Instance) {}

  protected:

    string WindowTitle;

    void InitApplication() { WindowTitle = string(First Instance); }

    void InitMainWindow() { SetMainWindow(

                          new TFrameWindow(0, WindowTitle.c_str())); }

};

int

OwlMain(int /* argc */, char* /* argv */[])

{

  return TTestApp().Run();

}

When multiple 16-bit instances of this application are open on the desktop, the first one has the title "First Instance" and each subsequent instance has the title "Additional Instance".

Because each instance of a 32-bit application is perceived as the first instance of the application, multiple 32-bit copies running at the same time all have the caption "First Instance".


See Also

Initializing Each New Instance

Initializing the Main Window


Initializing Each New Instance (ObjectWindows)

A user can run multiple instances (copies) of an application simultaneously. You can override TApplication::InitInstance to perform any initialization you need to do for each instance.

InitInstance calls InitMainWindow and then creates and shows the main window you set up in InitMainWindow. If you override InitInstance, be sure your new InitInstance calls TApplication::InitInstance. The following example shows how to use InitInstance to load an accelerator table.

void

TTestApp::InitInstance()

{

  TApplication::InitInstance();

  HAccTable = LoadAccelerators(MAKEINTRESOURCE(MYACCELS));

}


Initializing the Main Window (ObjectWindows)

See Also

By default, TApplication::InitMainWindow creates a frame window with the same name as the application object. This window is not very useful, because it cannot receive or process any user input. You must override InitMainWindow to create a window object that does process user input. Normally, your InitMainWindow function creates a TFrameWindow or TFrameWindow-derived object and calls the SetMainWindow function, a protected member function of TApplication. SetMainWindow takes one parameter, a pointer to a TFrameWindow object, and returns a pointer to the old main window. (If this is a new application that has not yet set up a main window, the return value is zero).

The following example shows a simple application that creates a TFrameWindow object and makes it the main window:

#include <owl\applicat.h>

#include <owl\framewin.h>

class TMyApplication: public TApplication

{

public:

  TMyApplication(): TApplication() {}

  virtual void InitMainWindow();

};

void

TMyApplication::InitMainWindow()

{

  SetMainWindow(new TFrameWindow(0, "My First Main Window"));

}

int

OwlMain(int argc, char* argv[])

{

  return TMyApplication("Wow!").Run();

}

When you run this application, the caption bar is titled "My First Main Window," and not "Wow!". The application name passed in the TApplication constructor is used only when you do not provide a main window. Once again, this example doesn't do a lot; there is still no provision for the frame window to process any user input. But once you have derived a window class that does interact with the user, you use the same simple method to display the window.


See Also

Changing the main window

Specifying the main window display mode

Window Objects


Specifying the Main Window Display Mode (ObjectWindows)

You can change how your application's main window is displayed by setting the TApplication data member nCmdShow, which corresponds to the WinMain parameter nCmdShow. You can set this variable as soon as the Run function begins, up until the time you call TApplication::InitInstance. This effectively means you can set nCmdShow in either the InitApplication or InitMainWindow function.

For example, suppose you want to display your window maximized whenever the user runs the application. You could set nCmdShow in your InitMainWindow function as follows:

#include <owl\applicat.h>

#include <owl\framewin.h>

class TMyApplication : public TApplication {

public :

  TMyApplication(char far *name) : TApplication(name) {}

  void InitMainWindow();

  };

void TMyApplication::InitMainWindow() {

  //Sets the main window.

  SetMainWindow(new TFrameWindow(0, "Maximum Window"));

  // Causes main window to be maximized when created.

  nCmdShow = SW_SHOWMAXIMIZED;

  }

int OwlMain(int argc, char* argv[])

{

  return TMyApplication("Wow!").Run();

}

nCmdShow can be set to any value appropriate as a parameter to the ShowWindow Windows function or the TWindow::Show member function, such as SW_HIDE, SW_SHOWNORMAL, SW_NORMAL, and so on.


Changing the Main Window (ObjectWindows)

You can use the SetMainWindow function to change your main window during the course of your application. SetMainWindow takes one parameter, a pointer to a TFrameWindow object, and returns a pointer to the old main window. (If this is a new application that hasn't yet set up a main window, the return value is 0). You can use this pointer to keep the old main window in case you want to restore it. Alternatively, you can use this pointer to delete the old main window object.


Application Message Handling (ObjectWindows)

See Also

After your application is initialized, the application object's MessageLoop starts running. MessageLoop is responsible for processing incoming messages from Windows. There are two ways you can refine message processing in an ObjectWindows application:

Extra message processing  (overriding default message handling functions)

Idle processing


See Also

Application Objects Overview (ObjectWindows)

Initializing Applications (ObjectWindows)

Closing Applications (ObjectWindows)

Using Control Libraries (ObjectWindows)


Extra Message Processing (ObjectWindows)

TApplication has member functions that provide the message-handling functionality for any ObjectWindows application. These functions are MessageLoop, IdleAction, PreProcessMenu, and ProcessAppMsg.


Idle Processing (ObjectWindows)

Idle processing lets your application take advantage of the idle time when there are no messages waiting (including user input). If there are no waiting messages, MessageLoop calls IdleAction.

To perform idle processing, override IdleAction to perform the actual idle processing. Since idle processing takes place while the user isn't doing anything, it should last only a short while. If you need to do anything that takes longer than a few tenths of a second, you should split it up into several processes.

IdleAction's parameter idleCount is a long specifying the number of times IdleAction was called between messages. You can use idleCount to choose between low-priority and high-priority idle processing. If idleCount reaches a high value, you know that a long period without user input has passed, so it's safe to perform low-priority idle processing.

Return true from IdleAction to call IdleAction back sooner.

You should always call the base class IdleAction function in addition to performing your own processing. If you are writing applications for Windows NT, you can also use multiple threads for background processing.


Closing Applications (ObjectWindows)

See Also

Users usually close a Windows application by choosing File|Exit or pressing Alt+F4. To give the user a chance to save any open files, it's important that the application be able to intercept such an attempt. TApplication lets you do that.

Changing Closing Behavior

TApplication and all window classes have or inherit the member function CanClose. Whenever an application object tries to shut down, it queries the main window's and document manager's CanClose function. (The exception is when dialog boxes are canceled by the user's clicking the Cancel button or pressing the Esc key, in which case the dialog is simply destroyed, bypassing the CanClose function.) If either the main window or document manager object has children, it calls the CanClose function for each child. In turn, each child calls the CanClose function of each of its children, if any, and so on.

The CanClose function gives each object a chance to prepare to be shut down. It also gives the object a chance to abort to the shutdown if necessary. When the object has completed its clean-up procedure, its CanClose function should return true.

If any of the CanClose functions called returns false, the shut-down procedure is aborted.

Closing the Application

The CanClose mechanism gives the application object, the main window, and any other windows a chance to either prepare for closing or prevent the closing from taking place. In the end, the application object approves the closing of the application. The normal closing sequence looks like this:

1.	Windows sends a WM_CLOSE message to the main window.

2.	The main window object's EvClose member function calls the application object's CanClose member function.

3.	The application object's CanClose member function calls the main window object's CanClose member function.

4.	The main window and document manager objects call CanClose for each of their child windows. The main window and document manager objects' CanClose functions return true only if all child windows' CanClose member functions return true.

5.	If both the main window and document manager objects' CanClose functions return true, the application object's CanClose function returns true.

6.	If the application object's CanClose function returns true, the EvClose function shuts down the main window and ends the application.

Modifying CanClose

CanClose should rarely return false. Instead, CanClose should perform any actions necessary to return true. CanClose should return false only if it's unable to do something necessary for orderly shutdown, or if the user wants to keep the application running.

For example, suppose you are creating a text editor. A possible procedure to follow in the CanClose member function would be to

1.	Check to see if the editor text had changed

2.	If so, prompt the user to ask whether the text should be saved before closing, using a message box with Yes, No, and Cancel buttons

3.	Check the return value from the message box:

 	If the user clicks Yes, save the file, then return true from the CanClose function.

 	If the user clicks No, simply return true from the CanClose function without saving the file.

 	If the user clicks Cancel, indicating that the user does not want to close the application yet, return false from the CanClose function without saving the file.


See Also

Application Message Handling (ObjectWindows)

Application Objects Overview (ObjectWindows)

Initializing Applications (ObjectWindows)

Using Control Libraries (ObjectWindows)


Using Control Libraries (ObjectWindows)

See Also

TApplication has functions for loading the Borland Custom Controls Library (BWCC.DLL for 16-bit applications and BWCC32.DLL for 32-bit applications) and the Microsoft 3-D Controls Library (contained in the file CTL3DV2.DLL for 16-bit applications and in CTL3D32.DLL for 32-bit applications). These DLLs are widely used to provide a standard look-and-feel for many applications.

Using the Borland Custom Controls Library

You can open and close the Borland Custom Controls Library using the function TApplication::EnableBWCC. EnableBWCC takes one parameter, a bool, and returns a void. When you pass true to EnableBWCC, the function loads the DLL if it is not already loaded. When you pass false to EnableBWCC, the function unloads the DLL if it is not already unloaded.

You can find out if the Borland Custom Controls Library DLL is loaded by calling the function TApplication::BWCCEnabled.. BWCCEnabled takes no parameters. If the DLL is loaded, BWCCEnabled returns true; if not, BWCCEnabled returns false.

After the DLL is loaded, you can use all the regular functionality of Borland Custom Controls Library. EnableBWCC automatically opens the correct library regardless of whether you have a 16- or a 32-bit application.

Using the Microsoft 3-D Controls Library

You can load and unload the Microsoft 3-D Controls Library with the function TApplication::EnableCtl3d. EnableCtl3d takes one parameter, a bool, and returns a void. When you pass true to EnableCtl3d, the function loads the DLL if it is not already loaded. When you pass false to EnableCtl3d, the function unloads the DLL if it is not already unloaded.

You can find out if the Microsoft 3-D Controls Library DLL is loaded by calling the function TApplication::Ctl3dEnabled. Ctl3dEnabled takes no parameters. If the DLL is loaded, Ctl3dEnabled returns true; if not, Ctl3dEnabled returns false.

To create a 3-D effect with non-ObjectWindows dialogs, you can turn autosubclassing on with the EnableCtl3dAutosubclass function. To use this function, first load the Microsoft 3-D Controls Library DLL with EnableCtl3d. EnableCtl3dAutosubclass takes one parameter, a bool, and returns a void. You can pass true to EnableCtl3dAutosubclass to turn autosubclassing on or false to turn autosubclassing off.

You can turn autosubclassing off immediately after creating the dialog box; it is not necessary to leave it on while displaying the dialog box.


See Also

Application Message Handling (ObjectWindows)

Application Objects Overview (ObjectWindows)

Closing Applications (ObjectWindows)

Initializing Applications (ObjectWindows)


Interface Objects (ObjectWindows)
Interface Objects Overview (ObjectWindows)

See Also

Instances of C++ classes representing windows, dialog boxes, and controls are called interface objects.

Interface objects are actually inside application objects. An interface object is an ObjectWindows class that is created and stored on the application's heap or stack, depending on how the object is allocated. The interface element, on the other hand, is actually a part of Windows. It is the actual window that is displayed on the screen.

Why Interface Objects?

One of the greatest difficulties of Windows programming is that controlling interface elements can be inconsistent and confusing. Sometimes you send a message to a window; other times you call a Windows API function. The conventions for similar types of operations often differ when those operations are performed with different kinds of elements.

ObjectWindows alleviates much of this difficulty by providing objects that encapsulate the interface elements. This insulates you from having to deal directly with Windows and provides a more uniform interface for controlling interface elements.

What Do Interface Objects Do?

An interface object provides member functions for creating, initializing, managing, and destroying its associated interface element. The member functions manage many of the details of Windows programming for you.

Interface objects also encapsulate the data needed to communicate with the interface element, such as handles and pointers to child and parent windows.

The relationship between an interface object and an interface element is similar to that between a file on disk and a C++ stream object. The stream object only represents an actual file on disk; you manipulate that file by manipulating the stream object. With ObjectWindows, interface objects represent the interface elements that Windows itself actually manages. You work with the object, and Windows takes care of maintaining the Windows element.


See Also

Creating Interface Objects (ObjectWindows)

Destroying Interface Objects (ObjectWindows)

Parent and Child Interface Elements (ObjectWindows)

Registering Window Classes (ObjectWindows)

The Generic Interface Object: TWindow (ObjectWindows)


The Generic Interface Object: TWindow (ObjectWindows)

See Also

ObjectWindows' interface objects are all derived from TWindow, which defines behavior common to all window, dialog box, and control objects. Classes like TFrameWindow, TDialog, and TControl are derived from TWindow and refine TWindow's generic behavior as needed.

As the common base class for all interface objects, TWindow provides uniform ways to

Maintain the relationship between interface objects and interface elements, including creating and destroying the objects and elements

Handle parent-child relationships between interface objects

Register new Windows window classes


See Also

Creating Interface Objects (ObjectWindows)

Destroying Interface Objects (ObjectWindows)

Interface Objects Overview (ObjectWindows)

Parent and Child Interface Elements (ObjectWindows)

Registering Window Classes (ObjectWindows)


Creating Interface Objects (ObjectWindows)

See Also

Setting up an interface object with its associated interface element requires two steps:

1.	Calling one of the interface object constructors, which constructs the interface object and sets its attributes

2.	Creating the interface element by telling Windows to create the interface object with a new interface element, depending on the kind of element, as follows:

When creating most interface elements, you call the interface object's Create member function (for example, TWindow::Create). Create also indirectly calls SetupWindow, which initializes the interface object by creating an interface element, such as a child window.

When creating a modal dialog box, you create the interface element by calling the interface object's Execute member function.

The association between the interface object and the interface element is maintained by the interface object's HWindow data member, a handle to a window.

In creating interface objects, the following topics will be helpful:

When Is a Window Handle Valid? (ObjectWindows)

Making Interface Elements Visible (ObjectWindows)

Object Properties (ObjectWindows)

Window Properties (ObjectWindows)


See Also

Destroying Interface Objects (ObjectWindows)

Interface Objects Overview (ObjectWindows)

Parent and Child Interface Elements (ObjectWindows)

Registering Window Classes (ObjectWindows)

The Generic Interface Object: TWindow (ObjectWindows)


When Is a Window Handle Valid? (ObjectWindows)

See Also

Normally under Windows, a newly created interface element receives a WM_CREATE message from Windows, and responds to it by initializing itself. ObjectWindows interface objects intercept the WM_CREATE message and call SetupWindow instead. SetupWindow is where you want to perform your own initialization.

If part of the interface object's initialization requires the interface element's window handle, you must perform that initialization after you call the base class's SetupWindow (for example, TFrameWindow::SetupWindow). Prior to the time you call the base class's SetupWindow, the window and its child windows have not been created, so HWindow is not valid and should not be used. You can easily test the validity of HWindow: if it has not been initialized, it is set to NULL. This example shows a typical call to SetupWindow:

class TMyWindow : public TFrameWindow

{

  public:

    TMyWindow(const char far* name) : TFrameWindow(name) {}

    void SetupWindow();

};

void

TMyWindow::SetupWindow()

{

  TFrameWindow::SetupWindow();

  .

  .

  .

}

Although it might seem odd that you cannot perform all initialization in the interface object's constructor, there is a good reason: after an interface element is created, you cannot change many of its characteristics. Therefore, a two-stage initialization is required: before and after the interface element is created.

The interface object's constructor is the place for initialization before the element is created, and SetupWindow is the place for initialization after the element is created. You can think of SetupWindow as the second part of the constructor.


See Also

Making Interface Elements Visible (ObjectWindows)

Object Properties (ObjectWindows)

Window Properties (ObjectWindows)


Making Interface Elements Visible (ObjectWindows)

See Also

Creating an object and its corresponding element does not mean that you will see something on the screen. When Windows creates the interface element, Windows checks to see if the element's style includes WS_VISIBLE. If it does, Windows displays the interface element; if it does not, the element is created but is not displayed onscreen.

TWindow's constructor sets WS_VISIBLE, so most interface objects are visible by default. But if your object loads a resource, that resource's style depends on what is defined in its resource file. If WS_VISIBLE is turned on in the resource's style, WS_VISIBLE is turned on for the object. If WS_VISIBLE is not turned on in the resource's style, WS_VISIBLE is turned off in the object's style. You can set WS_VISIBLE and other window styles in the interface object's Attr.Style data member.

For example, if you use TDialog to load a dialog resource that does not have WS_VISIBLE turned on, you must explicitly turn WS_VISIBLE on before attempting to display the dialog with Create.

You can find out whether an interface object is visible by calling IsWindowVisible, which returns true if the object is visible.

At any point after the interface element has been created, you can show or hide it by calling its Show member function with a value of true or false, respectively.


See Also

Object Properties (ObjectWindows)

TWindow::Create

TWindow::Show

When Is a Window Handle Valid? (ObjectWindows)

Window Properties (ObjectWindows)


Object Properties (ObjectWindows)

See Also

In addition to the attributes of its interface element, the interface object possesses certain attributes as an ObjectWindows object. You can query and change these properties and characteristics using the following functions:

SetFlag sets the specified flag for the object

ClearFlag clears the specified flag for the object

IsFlagSet returns true if the specified flag is set or false if the specified flag is not set

You can use the following flags with these functions:

wfAlias indicates whether the object is an alias.

wfAutoCreate indicates whether automatic creation is enabled for this object.

wfFromResource indicates whether the interface element is loaded from a resource.

wfShrinkToClient indicates whether the frame window should shrink to fit the size of the client window.

wfMainWindow indicates whether the window is the main window.

wfPredefinedClass indicates whether the window is a predefined Windows class.

wfTransfer indicates whether the window can use the data transfer mechanism.


See Also

Making Interface Elements Visible (ObjectWindows)

TWindow::ClearFlag

TWindow::IsFlagSet

TWindow::SetFlag

TWindowFlag enum describes the wfxxxx constants

When Is a Window Handle Valid? (ObjectWindows)

Window Properties (ObjectWindows)


Window Properties (ObjectWindows)

See Also

TWindow also provides functions that let you change resources and properties of the interface element. Because TWindow provides generic functionality for a large variety of objects, it does not provide very specific functions for resource and property manipulation. High-level objects provide much more specific functionality. But that specific functionality builds on and is in addition to the functionality provided by TWindow:

SetCaption sets the window caption to the string that you pass as a parameter.

GetWindowTextTitle returns a string containing the current window caption.

SetCursor sets the cursor of the instance, identified by the TModule parameter, to the cursor passed as a resource in the second parameter.

You can set the accelerator table for a window by assigning the resource ID (which can be a string or an integer) to Attr.AccelTable. For example, suppose you have an accelerator table resource called MY_ACCELS. You would assign the resource to Attr.AccelTable like this:

TMyWnd::TMyWnd(const char* title)

{

  Init(0, title);

  Attr.AccelTable = MY_ACCELS; // AccelTable can be assigned

}

The Init function in this example is used to initialize a the  base class of a derived window class.


See Also

Making Interface Elements Visible (ObjectWindows)

Object Properties (ObjectWindows)

When Is a Window Handle Valid? (ObjectWindows)


Destroying Interface Objects (ObjectWindows)

See Also

Destroying interface objects is a two-step process:

Destroying the interface element

Deleting the interface object

You can destroy the interface element without deleting the interface object, if you need to create and display the interface element again.


See Also

Creating Interface Objects (ObjectWindows)

Interface Objects Overview (ObjectWindows)

Parent and Child Interface Elements (ObjectWindows)

Registering Window Classes (ObjectWindows)

The Generic Interface Object: TWindow (ObjectWindows)


Destroying the Interface Element (ObjectWindows)

See Also

Destroying the interface element is the responsibility of the interface object's Destroy member function. Destroy destroys the interface elements by calling the DestroyWindow API function. When the interface element is destroyed, the interface object's HWindow data member is set to zero. Therefore, you can tell if an interface object is still associated with a valid interface element by checking its HWindow.

When a user closes a window on the screen, the following things happen:

Windows notifies the window.

The window goes through the CanClose mechanism to verify that the window should be closed.

If CanClose approves the closing of the window, the interface element is destroyed and the interface object is deleted.


See Also

Deleting the Interface Object (ObjectWindows)

Destroying the Interface Element (ObjectWindows)

TWindow::CanClose

TWindow::Destroy


Deleting the Interface Object (ObjectWindows)

See Also

If you destroy an interface element yourself so that you can redisplay the interface object later, you must make sure that you delete the interface object when you're done with it. Because an interface object is nothing more than a regular C++ object, you can delete it using the delete statement if you have dynamically allocated the object with new.

The following code illustrates how to destroy the interface element and the interface object:

TWindow *window = new TWindow(0, "My Window");

// ...

window->Destroy();

delete window;


See Also

Deleting the Interface Object (ObjectWindows)

Destroying the Interface Element (ObjectWindows)


Parent and Child Interface Elements (ObjectWindows)

See Also

In a Windows application, interface elements work together through parent-child links. A parent window controls its child windows, and Windows keeps track of the links. ObjectWindows maintains a parallel set of links between corresponding interface objects.

A child window is an interface element that is managed by another interface element. For example, list boxes are managed by the window or dialog box in which they appear. They are displayed only when their parent windows are displayed. In turn, dialog boxes are child windows managed by the windows that create them.

When you move or close the parent window, the child windows automatically close or move with it. The ultimate parent of all child windows in an application is the main window (there are a couple of exceptions: you can have windows and dialog boxes without parents and all main windows are children of the Windows desktop).

Review the following topics to understand more about parent and child interface elements:

Child-window Lists (ObjectWindows)

Constructing Child Windows (ObjectWindows)

Creating Child Interface Elements (ObjectWindows)

Destroying Windows (ObjectWindows)

Automatic Creation (ObjectWindows)

Manipulating Child Windows (ObjectWindows)


See Also

Creating Interface Objects (ObjectWindows)

Destroying Interface Objects (ObjectWindows)

Interface Objects Overview (ObjectWindows)

Parent and Child Interface Elements (ObjectWindows)

Registering Window Classes (ObjectWindows)

The Generic Interface Object: TWindow (ObjectWindows)


Child-window Lists (ObjectWindows)

See Also

When you construct a child-window object, you specify its parent as a parameter to its constructor. A child-window object keeps track of its parent through the Parent data member. A parent keeps track of its child-window objects in a private data member called ChildList. Each parent maintains its list of child windows automatically.

You can access an object's child windows using the window iterator member functions FirstThat and ForEach.


See Also

Automatic Creation (ObjectWindows)

Constructing Child Windows (ObjectWindows)

Creating Child Interface Elements (ObjectWindows)

Destroying Windows (ObjectWindows)

Manipulating Child Windows (ObjectWindows)


Constructing Child Windows (ObjectWindows)

See Also

As with all interface objects, child-window objects get created in two steps: constructing the interface object and creating the interface element. If you construct child-window objects in the constructor of the parent window, their interface elements are automatically created when the parent is, assuming that automatic creation is enabled for the child windows. By default, automatic creation is enabled for all ObjectWindows objects based on TWindow, with the exception of TDialog.

For example, the constructor for a window object derived from TWindow that contains three button child windows would look like this:

TTestWindow::TTestWindow(TWindow *parent, const char far *title)

{

  Init(parent, title);

  button1 = new TButton(this, ID_BUTTON1, "Show",

                        190, 270, 65, 20, false);

  button2 = new TButton(this, ID_BUTTON2, "Hide",

                        275, 270, 65, 20, false);

  button3 = new TButton(this, ID_BUTTON3, "Transfer",

                        360, 270, 65, 20, false);

}

Note the use of the this pointer to link the child windows with their parent. Interface object constructors automatically add themselves to their parents' child window lists. When an instance of TTestWindow is created, the three buttons are automatically displayed in the window.


See Also

Child-window Lists (ObjectWindows)

Creating Child Interface Elements (ObjectWindows)

Destroying Windows (ObjectWindows)

Manipulating Child Windows (ObjectWindows)


Creating Child Interface Elements (ObjectWindows)

See Also

If you do not construct child-window objects in their parent window object's constructor, they will not be automatically created and displayed when the parent is. You can then create them yourself using Create or, in the case of modal dialog boxes, Execute. In this context, creating means instantiating an interface element.

For example, suppose you have two buttons displayed when the main window is created, one labeled Show and the other labeled Hide. When the user presses the Show button, you want to display a third button labeled Transfer. When the user presses the Hide button, you want to remove the Transfer button:

class TTestWindow : public TFrameWindow

{

  TButton *button1, *button2, *button3;

  public:

    TTestWindow(TWindow *parent, const char far *title);

    void

    EvButton1()

    {

      if(!button3->HWindow) {

        button3->Create();

      }

    }

    void

    EvButton2()

    {

      if(button3->HWindow)

        button3->Destroy();

    }

    void

    EvButton3()

    {

      MessageBeep(-1);

    }

  DECLARE_RESPONSE_TABLE(TTestWindow);

};

DEFINE_RESPONSE_TABLE1(TTestWindow, TFrameWindow)

  EV_COMMAND(ID_BUTTON1, EvButton1),

  EV_COMMAND(ID_BUTTON2, EvButton2),

  EV_COMMAND(ID_BUTTON3, EvButton3),

END_RESPONSE_TABLE;

TTestWindow::TTestWindow(TWindow *parent, const char far *title)

{

  Init(parent, title);

  button1 = new TButton(this, ID_BUTTON1, "Show",

                        10, 10, 75, 25, false);

  button2 = new TButton(this, ID_BUTTON2, "Hide",

                        95, 10, 75, 25, false);

  button3 = new TButton(this, ID_BUTTON3, "Transfer",

                        180, 10, 75, 25, false);

  button3->DisableAutoCreate();

}

The call to DisableAutoCreate in the constructor prevents the Transfer button from being displayed when TTestWindow is created. The conditional tests in the EvButton1 and EvButton2 functions work by testing the validity of the HWindow data member of the button3 interface object; if the Transfer button is already being displayed, EvButton1 does not try to display it again, and EvButton2 does not try to destroy the Transfer button if it is not being displayed.


See Also

Automatic Creation (ObjectWindows)

Child-window Lists (ObjectWindows)

Constructing Child Windows (ObjectWindows)

Destroying Windows (ObjectWindows)

Manipulating Child Windows (ObjectWindows)

TButton class

TFrameWindow class


Destroying Windows (ObjectWindows)

See Also

Destroying a parent window also destroys all its child windows. You do not need to explicitly destroy child windows or delete child window interface objects. The same is true for the CanClose mechanism; CanClose for a parent window calls CanClose for all its children. The parent's CanClose returns true only if all its children return true for CanClose.

When you destroy an object's interface element, it enables automatic creation for all its children, regardless of whether automatic creation was on or off before. This way, when you create the parent, all the children are restored in the state they were in before their parent was destroyed. You can use this technique to destroy an interface element, and then re-create it in the same state it was in when you destroyed it.

To prevent this behavior, you must explicitly turn off automatic creation for any child objects you do not want to have created automatically.


See Also

Automatic Creation (ObjectWindows)

Child-window Lists (ObjectWindows)

Constructing Child Windows (ObjectWindows)

Creating Child Interface Elements (ObjectWindows)

Manipulating Child Windows (ObjectWindows)


Automatic Creation (ObjectWindows)

See Also

When automatic creation is enabled for a child interface object before its parent is created, the child is automatically created at the same time the parent is created. This is true for all the parent object's children.

To explicitly exclude a child window from the automatic create-and-show mechanism, call the DisableAutoCreate member function in the child object's constructor. To explicitly add a child window (such as a dialog box, which would normally be excluded) to the automatic create-and-show mechanism, call the EnableAutoCreate member function in the child object's constructor.

By default automatic creation is enabled for all ObjectWindows classes except dialog boxes.


See Also

Child-window Lists (ObjectWindows)

Constructing Child Windows (ObjectWindows)

Creating Child Interface Elements (ObjectWindows)

Destroying Windows (ObjectWindows)

Manipulating Child Windows (ObjectWindows)


Manipulating Child Windows (ObjectWindows)

See Also

TWindow provides two iterator functions, ForEach and FirstThat, that let you perform operations either on all the children in the parent's child list or on a single child at a time. TWindow also provides a number of other functions that let you determine the number of children in the child list, move through them one at a time, or move to the top or bottom of the list.

The following topics explain more about manipulating child windows:

Operating On All Children: ForEach (ObjectWindows)

Finding a Specific Child (ObjectWindows)

Working with the Child List (ObjectWindows)


See Also

Automatic Creation (ObjectWindows)

Child-window Lists (ObjectWindows)

Constructing Child Windows (ObjectWindows)

Creating Child Interface Elements (ObjectWindows)

Destroying Windows (ObjectWindows)


Operating On All Children: ForEach (ObjectWindows)

See Also

You might want to perform some operation on each of a parent window's child windows. The iterator function ForEach takes a pointer to a function. The function can be either a member function or a stand-alone function. The function should take a TWindow * and a void * argument. ForEach calls the function once for each child. The child is passed as the TWindow *. The void * defaults to 0. You can use the void * to pass any arguments you want to your function.

After ForEach has called your function, you often need to be careful when dealing with the child object. Although the object is passed as a TWindow *, it is actually usually a descendant of TWindow. To make sure the child object is handled correctly, you should use the TYPESAFE_DOWNCAST macro to cast the TWindow * to a TClass *, where TClass is whatever type the child object is.

For example, suppose you want to check all the check box child windows in a parent window:

void CheckTheBox(TWindow* win, void*)

{

  TCheckbox *cb = TYPESAFE_DOWNCAST(win, TCheckbox);

  if(cb)

    cb->Check();

}

void TMDIFileWindow::CheckAllBoxes()

{

  ForEach(CheckTheBox);

}

If the class you're downcasting to (in this case from a TWindow to a TCheckbox) is virtually derived from its base, you must use the TYPESAFE_DOWNCAST macro to make the assignment. In this case, TCheckbox is not virtually derived from TWindow, making the TYPESAFE_DOWNCAST macro seem superfluous in this case.

But TYPESAFE_DOWNCAST returns 0 if the cast could not be performed. This is how the TYPESAFE_DOWNCAST macro is used here, because not all of the children are necessarily of type TCheckbox. If a child of type TControlBar were encountered, the value of cb would be 0, thus assuring that you do not try to check a control bar.


See Also

Finding a Specific Child (ObjectWindows)

Working with the Child List (ObjectWindows)


Finding a Specific Child (ObjectWindows)

See Also

You might want to perform a function only on a specific child window. For example, if you wanted to find the first check box that is checked in a parent window with several check boxes, you would use TWindow::FirstThat:

bool IsThisBoxChecked(TWindow* cb, void*)

{

  return cb ?

    (cb->GetCheck == BF_CHECKED) :

    false;

}

TCheckBox* TMDIFileWindow::GetFirstChecked()

{

  return FirstThat(IsThisBoxChecked);

}


See Also

Operating On All Children: ForEach (ObjectWindows)

Working with the Child List (ObjectWindows)


Working with the Child List (ObjectWindows)

See Also

In addition to the iterator functions ForEach and FirstThat, TWindow provides a number of functions that let you locate and manipulate a single child window:

NumChildren returns an unsigned. This value indicates the total number of child windows in the child list.

GetFirstChild returns a TWindow * that points to the first entry in the child list.

GetLastChild returns a TWindow * that points to the last entry in the child list.

Next returns a TWindow * that points to the next entry in the child list.

Previous returns a TWindow * that points to the prior entry in the child list.


See Also

Finding a Specific Child (ObjectWindows)

Operating On All Children: ForEach (ObjectWindows)


Registering Window Classes (ObjectWindows)

See Also

Whenever you create an interface element from an interface object using the Create or Execute functions, the object checks to see if another object of the same type has registered with Windows. If so, the element is created based on the existing Windows registration class. If not, the object automatically registers itself, then is created based on the class just registered.

This removes the burden from the programmer of making sure all window classes are registered before use.


See Also

Creating Interface Objects (ObjectWindows)

Destroying Interface Objects (ObjectWindows)

Interface Objects Overview (ObjectWindows)

Parent and Child Interface Elements (ObjectWindows)

The Generic Interface Object: TWindow (ObjectWindows)


Event Handling Overview (ObjectWindows)

Response tables are the method you use to handle all events in an ObjectWindows application. There are four main steps to using ObjectWindows response tables:

1.	Declare the response table.

2.	Define the response table.

3.	Define the response table entries.

4.	Declare and define the response member functions.

Note: ObjectWindows response tables use a set of macros defined in owl\eventhan.h. Since this file is already included by owl\module.h, owl\applicat.h, and owl\window.h, there is usually no need to explicitly include eventhan.h.

Response Table Features

ObjectWindows response tables are a major improvement over other methods of handling Windows events and messages, including switch statements (such as those in standard C Windows programs) and schemes used in other types of application frameworks. Unlike other methods of event handling, ObjectWindows response tables provide:

Automatic message cracking for predefined command messages, thus eliminating the need for manual cracking of the WPARAM and LPARAM values

Compile-time error and type checking, which checks the event-handling function's return type and parameter types

Ability to have one function handle multiple messages

Support for multiple inheritance, enabling each derived class to build on top of the base class or classes' response tables

Portability across platforms by not relying on product-specific compiler extensions

Easy handling of command, registered, child ID notification, and custom messages, using the predefined response table macros


Declaring Response Tables (ObjectWindows)

See Also

Because the response table is a member of an ObjectWindows class, you must declare the response table when you define the class. ObjectWindows provides the DECLARE_RESPONSE_TABLE macro to hide the actual template syntax that response tables use.

The DECLARE_RESPONSE_TABLE macro takes a single argument, the name of the class for which the response table is being declared. Add the macro at the end of your class definition.

Example

TMyFrame, derived from TFrameWindow, would be defined like this:

class TMyFrame : public TFrameWindow

{

  .

  .

  .

  DECLARE_RESPONSE_TABLE(TMyFrame);

};

It does not matter what the access level (public, protected, or private) is at the point where you declare the response table: The DECLARE_RESPONSE_TABLE macro sets up its own access levels when it is expanded by the preprocessor. Because the access level is reset at the point where you declare the response table, you must make the DECLARE_RESPONSE_TABLE macro the last element in your class declaration. Any members declared after the macro will have unpredictable access levels.


See Also

Defining Response Table Entries (ObjectWindows)

Defining Response Tables (ObjectWindows)


Defining Response Tables (ObjectWindows)

See Also

After you have declared a response table, you must define it. Response table definitions must appear outside the class definition.

ObjectWindows provides the DEFINE_RESPONSE_TABLEX macro to help define response tables. The value of X depends on your class's inheritance and is a number equal to the number of immediate base classes your class has. END_RESPONSE_TABLE ends the event response table definition.

To define your response table,

1.	Begin the response table definition for your class using the DEFINE_RESPONSE_TABLEX macro. DEFINE_RESPONSE_TABLEX takes X + 1 arguments: the name of the class you are defining the response table for and the name of each immediate base class

2.	Fill in the response table entries

3.	End the response table definition using the END_RESPONSE_TABLE macro.

Example

For example, the response table definition for TMyFrame, derived from TFrameWindow, would look like this:

DEFINE_RESPONSE_TABLE1(TMyFrame, TFrameWindow)

  EV_WM_LBUTTONDOWN,

  EV_WM_LBUTTONUP,

  EV_WM_MOUSEMOVE,

  EV_WM_RBUTTONDOWN,

END_RESPONSE_TABLE;

You must always place a comma after each response table entry and a semicolon after the END_RESPONSE_TABLE macro.


See Also

Declaring Response Tables (ObjectWindows)

Defining Response Table Entries (ObjectWindows)


Defining Response Table Entries (ObjectWindows)

See Also

Response table entries associate a Windows event with a particular function. When a window or control receives a message, it checks its response table to see if there is an entry for that message. If there is, it passes the message on to that function. If not, it passes the message up to its parent. If the window is the main window, it passes the message on to the application object. If the application object doesn't have a response entry for that particular message, the message is handled by ObjectWindows default processing.

ObjectWindows provides a large number of macros for response table entries. These include:

Command message macros that let you handle command messages and route them to a specified function.

Standard Windows message macros for handling Windows messages.

Registered messages (messages returned by RegisterWindowMessage).

Child ID notification macros that let you handle child ID notification codes at the child or the parent.

Control notification macros that handle messages from specialized controls such as buttons, combo boxes, edit controls, list boxes, and so on.

Document manager message macros to notify the application that a document or view has been created or destroyed and to notify views about events from the document manager.

VBX control notifications.


See Also

Child ID Notification Message Macros (ObjectWindows)

Command Message Macros (ObjectWindows)

Declaring Response Tables (ObjectWindows)

Defining Response Tables (ObjectWindows)

Windows Message Macros (ObjectWindows)


Command Message Macros (ObjectWindows)

See Also

ObjectWindows provides a large number of macros, called command message macros, that let you assign command messages to any function. The only requirement is that the signature of the function you specify to handle a message must match the signature required by the macro for that message. The different types of command message macros are listed in the following table:

Macro and Prototype	Description

macro:	EV_COMMAND(CMD, UserName)	Calls the member function UserName when

prototype:	void UserName()	the command message CMD is received.

macro:	EV_COMMAND_AND_ID(CMD, UserName)	Calls the member function UserName when

prototype:	void UserName(WPARAM)	the command message CMD is received. Passes the command's ID (the WPARAM parameter) to the function.

macro:	EV_COMMAND_ENABLE(CMD, UserName)	Used to automatically enable and disable

prototype:	void UserName(TCommandEnabler&)	command controls such as menu items, tool bar buttons, and so on.

The following table shows message macros that let you pass the raw, unprocessed message on to the event-handling function. These message macros handle any kind of generic message and registered message.

Macro and Prototype	Description

macro:	EV_MESSAGE(MSG, UserName)	Calls the member function UserName when

prototype:	LRESULT UserName(WPARAM, LPARAM)	the user-defined message MSG is received. MSG is passed to UserName without modification.

macro:	EV_REGISTERED(MSG, UserName)	Calls the member function UserName when

prototype:	LRESULT UserName(WPARAM, LPARAM)	the registered message MSG is received. MSG is passed to UserName without modification.

Matching Function Signatures

It is very important that you correctly match the function signature with the macro that you use in the response table definition. For example, suppose you have the following code:

class TMyFrame : public TFrameWindow {

public:

  TMyFrame(TWindow* parent, const char* name) :
    TFrameWindow(parent,name) ()

protected:

  void CmAdvise();

  DECLARE_RESPONSE_TABLE(TMyFrame);

};

DEFINE_RESPONSE_TABLE(TMyFrame, TFrameWindow)

  EV_COMMAND_AND_ID(CM_ADVISE, CmAdvise),

END_RESPONSE_TABLE;

void TMyFrame::CmAdvise() {

  .

  .

  .

}

This code produces a compile-time error because the EV_COMMAND_AND_ID macro requires a function that returns void and takes a single WPARAM parameter. In this example, the function correctly returns a void, but incorrectly takes no parameters.

To make this code compile correctly, change the member declaration and function definition of TMyFrame::CmAdvise to

void TMyFrame::CmAdvise(WPARAM cmd);


See Also

Child ID Notification Message Macros (ObjectWindows)

Windows Message Macros (ObjectWindows)


Windows Message Macros (ObjectWindows)

See Also

ObjectWindows provides predefined macros for all standard Windows messages. You can use these macros to handle standard Windows messages in one of your class's member functions.

To determine the name of the macro, preface the message name with EV_. For example, the macro that handles the WM_PAINT message is EV_WM_PAINT. The macro that handles the WM_LBUTTONDOWN message is EV_WM_LBUTTONDOWN.

These predefined macros pass the message on to functions with predefined names. To determine the function name, remove the WM_ from the message name, add Ev to the remaining part of the message name and convert the name to lowercase with capital letters at word boundaries. For example, the WM_PAINT message is passed to a function called EvPaint. The WM_LBUTTONDOWN message is passed to a function called EvLButtonDown.

The advantage of using these Windows message macros is that the Windows message is automatically cracked; that is, the parameters that are normally encoded in the LPARAM and WPARAM parameters are broken out into their constituent parts and passed to the event-handling function as individual parameters.

For example, the EV_WM_CTLCOLOR macro passes the cracked parameters to an event-handling function with the following signature:

HBRUSH EvCtlColor(HDC hDCChild, HWND hWndChild, uint nCtrlType);

Message cracking provides for strict C++ compile-time type checking and helps you catch errors as you compile your code rather when you run your code. It also helps when migrating applications from 16-bit to 32-bit and vice versa. See Standard Windows Messages for lists showing each Windows message response table macro and the signature of the corresponding event-handling function.

To use a predefined Windows message macro, add the macro to your response table and add the appropriate member function with the correct name and signature to your class, then define the member function to handle the message the way you want it to.

Example

Suppose you want to perform some operation when your TMyFrame window object receives the WM_ERASEBKGND message. The code would look like this:

class TMyFrame : public TFrameWindow {

public:

  bool EvEraseBkgnd(HDC);

  DECLARE_RESPONSE_TABLE(TMyFrame);

};

DEFINE_RESPONSE_TABLE(TMyFrame, TFrameWindow)

  EV_WM_ERASEBKGND,

END_RESPONSE_TABLE;

bool TMyFrame::EvEraseBkgnd(HDC hdc) {

  .

  .

  .

}


See Also

Child ID Notification Message Macros (ObjectWindows)

Command Message Macros (ObjectWindows)

Event Handlers (ObjectWindows)

Windows Message Macros (ObjectWindows)


Child ID Notification Message Macros (ObjectWindows)

See Also

The child ID notification message macros provide a number of different ways to handle child ID notification messages. You can handle notification codes from multiple children with a single function, pass all notification codes from a child to a response window, or handle the notification code at the child.

You use these macros to facilitate controlling and communicating with child controls. The different types of child ID notification message macros are listed in the following table:

Macro and Prototype	Description

macro:	EV_CHILD_NOTIFY(ID,Code,UserName)	Dispatches message and notification code

prototype:	void UserName()	to the member function UserName.

macro:	EV_CHILD_NOTIFY_AND_CODE(Id, 	Dispatches message Id with the notification

  Code, UserName)	code Code to the function UserName.

prototype:	void UserName(WPARAM code)

macro:	EV_CHILD_NOTIFY_ALL_CODES(Id, 	Dispatches message Id to the function

  UserName)	UserName, regardless of the message's

prototype:	void UserName(WPARAM code)	notification code.

macro:	EV_NOTIFY_AT_CHILD(Code, UserName)	Dispatches the notification code Code

prototype:	void UserName()	to the child-object member function UserName.

These macros provide different methods for handling child ID notification codes. For more about these macros, see

EV_CHILD_NOTIFY

EV_CHILD_NOTIFY_ALL_CODES

EV_CHILD_NOTIFY_AND_CODE

EV_CHILD_NOTIFY_AT_CHILD


See Also

Child ID Notification Message Macros (ObjectWindows)

Command Message Macros (ObjectWindows)

OWL Event Handlers

Windows Message Macros (ObjectWindows)


EV_CHILD_NOTIFY

See Also

If you want child ID notifications to be handled at the child's parent window, use EV_CHILD_NOTIFY, which passes the notification code as a parameter and lets multiple child ID notifications be handled with a single function. This macro also saves you from having to handle each child's notification message in separate response tables for each control. Instead, each message is handled at the parent, enabling, for example, a dialog box to handle all its controls in its response table.

Examples

Suppose you have a dialog box called TTestDialog that has four buttons. The buttons IDs are ID_BUTTON1, ID_BUTTON2, ID_BUTTON3, and ID_BUTTON4. When the user clicks a button, you want a single function to handle the event, regardless of which button was pressed. If the user double-clicks a button, you want a special function to handle the event.

The code looks like this:

class TTestDialog : public TDialog {

public:

  TTestDialog(TWindow* parent, TResId resId);

  void HandleClick();

  void HandleDblClick1();

  void HandleDblClick2();

  void HandleDblClick3();

  void HandleDblClick4();

  DECLARE_RESPONSE_TABLE(TTestDialog);

};

DEFINE_RESPONSE_TABLE1(TTestDialog, TDialog)

  EV_CHILD_NOTIFY(ID_BUTTON1, BN_CLICKED, HandleClick),

  EV_CHILD_NOTIFY(ID_BUTTON2, BN_CLICKED, HandleClick),

  EV_CHILD_NOTIFY(ID_BUTTON3, BN_CLICKED, HandleClick),

  EV_CHILD_NOTIFY(ID_BUTTON4, BN_CLICKED, HandleClick),

  EV_CHILD_NOTIFY(ID_BUTTON1, BN_DOUBLECLICKED, HandleDblClick1),

  EV_CHILD_NOTIFY(ID_BUTTON2, BN_DOUBLECLICKED, HandleDblClick2),

  EV_CHILD_NOTIFY(ID_BUTTON3, BN_DOUBLECLICKED, HandleDblClick3),

  EV_CHILD_NOTIFY(ID_BUTTON4, BN_DOUBLECLICKED, HandleDblClick4),

END_RESPONSE_TABLE;


See Also

Child ID Notification Message Macros (ObjectWindows)

EV_CHILD_NOTIFY_ALL_CODES

EV_CHILD_NOTIFY_AND_CODE

EV_CHILD_NOTIFY_AT_CHILD


EV_CHILD_NOTIFY_ALL_CODES

See Also

If you want all notification codes from the child to be passed to the parent window, use EV_CHILD_NOTIFY_ALL_CODES, the generic handler for child ID notifications. For example, the sample program BUTTONX.CPP defines this response table:

DEFINE_RESPONSE_TABLE1(TTestWindow, TWindow)

  EV_COMMAND(ID_BUTTON, HandleButtonMsg),

  EV_COMMAND(ID_CHECKBOX, HandleCheckBoxMsg),

  EV_CHILD_NOTIFY_ALL_CODES(ID_GROUPBOX, HandleGroupBoxMsg),

END_RESPONSE_TABLE;

This table handles button, check box, and group box messages. In this case, the parent window (TTestWindow) gets all notification messages sent by the child (ID_GROUPBOX). The EV_CHILD_NOTIFY_ALL_CODES macro uses the user-defined function HandleGroupBoxMsg to process these messages. As a result, if the user clicks one of the group box radio buttons, a message box appears that tells the user which button was selected.


See Also

Child ID Notification Message Macros (ObjectWindows)

EV_CHILD_NOTIFY

EV_CHILD_NOTIFY_AND_CODE

EV_CHILD_NOTIFY_AT_CHILD


EV_CHILD_NOTIFY_AND_CODE

See Also

You can use the macro EV_CHILD_NOTIFY_AND_CODE if you want the parent window to handle more than one message using the same function. For example:

DEFINE_RESPONSE_TABLE1(TTestWindow, TWindow)

  EV_CHILD_NOTIFY_AND_CODE(ID_GROUPBOX, SomeNotifyCode,
    HandleThisMessage),

  EV_CHILD_NOTIFY_AND_CODE(ID_GROUPBOX, AnotherNotifyCode,
    HandleThisMessage),

END_RESPONSE_TABLE;

Note:	If your window has several different messages to handle and uses several different functions to handle these messages, it's better to use EV_CHILD_NOTIFY_AND_CODE instead of EV_CHILD_NOTIFY because EV_CHILD_NOTIFY message-handling function receives no parameters and therefore doesn't know which message it's handling.


See Also

Child ID Notification Message Macros (ObjectWindows)

EV_CHILD_NOTIFY

EV_CHILD_NOTIFY_ALL_CODES

EV_CHILD_NOTIFY_AT_CHILD


EV_CHILD_NOTIFY_AT_CHILD

See Also

To handle child ID notifications at the child window, use EV_CHILD_NOTIFY_AT_CHILD. The sample program NOTITEST.CPP contains the following response table:

DEFINE_RESPONSE_TABLE1(TBeepButton, TButton)

  EV_NOTIFY_AT_CHILD(BN_CLICKED, BnClicked),

END_RESPONSE_TABLE;

This response table uses the macro EV_NOTIFY_AT_CHILD to tell the child window (TBeepButton) to handle the notification code (BN_CLICKED) using the function BnClicked.


See Also

Child ID Notification Message Macros (ObjectWindows)

EV_CHILD_NOTIFY

EV_CHILD_NOTIFY_ALL_CODES

EV_CHILD_NOTIFY_AND_CODE


Command Enabling Overview

See Also

ObjectWindows provides a mechanism, command enabling, that you can use to dynamically change the appearance of controls to indicate if a feature is available or to indicate the state of the application. Typical changes are dimming the control, adding or deleting a check next to the control, or changing the text of menu items.

The following topics explain how to use command enabling in your programs:

Handling Command-Enabling Messages

Enabling and Disabling Command Items

Changing Menu Item Text

Toggling Command Items


See Also

Constructing Menu Objects

Gadget and Gadget Window Objects

TCommandEnabler class


Handling Command-Enabling Messages

See Also

The basic idea behind command enabling is that the decision to enable or disable a function should be made by the object that handles the command. ObjectWindows does this by sending the WM_COMMAND_ENABLE message through the same command chain as a WM_COMMAND event. The event is then received by the window that implements the functionality that you are enabling or disabling.

When a WM_COMMAND_ENABLE message is sent depends on the type of command item that is affected. TFrameWindow performs command enabling for menu items when the user clicks a menu, spawning a WM_INITMENUPOPUP message. Gadget windows perform command enabling for control bar buttons during the window's idle processing.

To handle command-enabling messages for a particular function,

1.	Add a member function to the window class to handle the command-enabling message. This function should return void and take a single parameter, a reference to a TCommandEnabler object. The abstract base class TCommandEnabler is declared in the  header file window.h.

2.	Place the EV_COMMAND_ENABLE macro in the parent window's response table. This macro takes two parameters, the command identifier and the name of the handler function.

Suppose you have a frame window class that handles a File|Save menu command that uses the command identifier CM_FILESAVE. The class definition would look something like this:

class TMyFrame : public TFrameWindow

{

  public:

    TMyFrame(TWindow* parent = 0, char* title = 0)

      : TFrameWindow(parent, title), IsDirty(false) {}

  protected:

    voidCmFileSave();

  DECLARE_RESPONSE_TABLE(TMyFrame);

};

DEFINE_RESPONSE_TABLE(TMyFrame)

  EV_COMMAND(CM_FILESAVE,CmFileSave),

END_RESPONSE_TABLE;

If you did not want the user to be able to access the File|Save command if the file had not been modified since it was opened or last saved, you could add a handler function and response table macro to affect the CmFileSave function like this:

class TMyFrame : public TFrameWindow

{

  public:

    TMyFrame(TWindow *parent = 0, char *title = 0)

      : TFrameWindow(parent, title), IsDirty(false) {}

  protected:

    void CmFileSave();

    // This is the command-enabling handler function.

    void CeFileSave(TCommandEnabler& commandEnabler);

  DECLARE_RESPONSE_TABLE(TMyFrame);

};

DEFINE_RESPONSE_TABLE(TMyFrame)

  EV_COMMAND(CM_FILESAVE, CmFileSave),

  EV_COMMAND_ENABLE(CM_FILESAVE, CeFileSave),

END_RESPONSE_TABLE;

Notice that the EV_COMMAND macro and the EV_COMMAND_ENABLE macro both use the same command identifier. Often a single function can be accessed through multiple means. For example, many applications let you open a file through a menu item and also through a button on the control bar. Command enabling in ObjectWindows lets you use a single, common identifier to do command enabling for all means of accessing a function, making it unnecessary to write separate command-enabling functions for each different command item.


See Also

Event Handling Overview

TCommandEnabler class

Enabling and Disabling Command Items

Changing Menu Item Text

Toggling Command Items


Enabling and Disabling Command Items

See Also

Enabling and disabling command items is as simple as calling the Enable function in your handler function. You decide the criteria for enabling and disabling a particular item. For example, if a particular library is not available, you might want to disable any commands that access that library. If your application handles files in a number of different formats, you might want to disable commands that are not appropriate to the current format.

To enable or disable a command,

1.	Add the command-enabling handler function and response table macro to your window class (as shown in Handling Command-Enabling Messages).

2.	Define the handler function.

3.	Inside the handler function, call the Enable member function of the command-enabling object passed into the handler function. The Enable function takes a single bool parameter. Call Enable with the value of the parameter set either to true to enable the command or to false to disable the command.

The following sample class has a bool flag, IsDirty, to tell if the file has been modified since it was opened or last saved, and a CeFileSave function to enable and disable the File|Save command:

class TMyFrame : public TFrameWindow

{

  public:

    TMyFrame(TWindow *parent = 0, char *title = 0)

      : TFrameWindow(parent, title), IsDirty(false) {}

  protected:

    bool IsDirty;

    void CmFileSave();

    // This is the command-enabling handler function.

    void CeFileSave(TCommandEnabler& commandEnabler);

  DECLARE_RESPONSE_TABLE(TMyFrame);

};

DEFINE_RESPONSE_TABLE(TMyFrame)

  EV_COMMAND(CM_FILESAVE, CmFileSave),

  EV_COMMAND_ENABLE(CM_FILESAVE, CeFileSave),

END_RESPONSE_TABLE;

void

TMyFrame::CeFileSave(TCommandEnabler& ce)

{

  ce.Enable(IsDirty);

}

CeFileSave checks the IsDirty flag. If IsDirty is false (the file has not been modified), it disables the CmFileSave command by calling Enable, passing false as the parameter. If IsDirty is true (the file has been modified), CeFileSave enables the CmFileSave command, passing true as the parameter. Because you want to call Enable with the true parameter when IsDirty is true and vice versa, you can just pass IsDirty as the parameter to Enable.

This method of enabling and disabling a command works for both menu items and button gadgets. In the preceding example, if you have both a control bar button and a menu item that send the CM_FILESAVE command, both commands are implemented in the CmFileSave function. Similarly, command enabling for the control bar button and the menu item is implemented in the CeFileSave function.


See Also

Handling Command-Enabling Messages

Changing Menu Item Text

Toggling Command Items


Changing Menu Item Text

See Also

Changing the text of a menu item is done with the SetText function. To change the text of a menu item,

1.	Add the command-enabling handler function and response table macro to your window class (as shown in Handling Command-Enabling Messages).

2.	Define the handler function.

3.	In the handler function, call the SetText member function of the command-enabling object passed into the handler function. SetText takes a single parameter, a const far char*, and returns void. The character array parameter should contain the new text for the menu item.

Note: If you are setting the text for a menu item and turning on a check mark for that menu item in the same function, you must call SetText before you call SetCheck. Reversing this order removes the check mark.

Suppose your application supports three different file formats: text, binary, and encrypted, and you want the File|Save menu item to reflect the format of the file being saved. Here is the sample class from Handling Command-Enabling Messages, modified with an enum type, TFormat, and a TFormat data member called Format:

class TMyFrame : public TFrameWindow

{

  public:

    TMyFrame(TWindow *parent = 0, char *title = 0);

    enum TFormat {Text, Binary, Encrypted};

  protected:

    TFormat Format;

    void CmFileSave();

    // This is the command-enabling handler function.

    void CeFileSave(TCommandEnabler& commandEnabler);

  DECLARE_RESPONSE_TABLE(TMyFrame);

};

DEFINE_RESPONSE_TABLE(TMyFrame)

  EV_COMMAND(CM_FILESAVE, CmFileSave),

  EV_COMMAND_ENABLE(CM_FILESAVE, CeFileSave),

END_RESPONSE_TABLE;

void

TMyFrame::CeFileSave(TCommandEnabler& ce)

{

  switch(Format) {

    case Text:

      ce.SetText("Save as text file");

      break;

    case Binary:

      ce.SetText("Save as binary file");

      break;

    case Encrypted:

      ce.SetText("Save as encrypted file");

      break;

    default:

      ce.SetText("Save");

  }

}


See Also

Enabling and Disabling Command Items

Handling Command-Enabling Messages

Toggling Command Items


Toggling Command Items

See Also

You can use command-item toggling to provide the users of your applications visual cues about what functions are enabled, various application states, and so on. Anything that can be presented in a Boolean fashion, such as on and off, in and out, and so on, can be represented by command-item toggling.

There are two different types of toggling implemented in ObjectWindows, but both are implemented the same way.

You can turn check marks beside menu items on and off.

You can check and uncheck button gadgets to make the gadget stand out when it is off and be recessed and grayed when it is on.

There is also a third, indeterminate state, the meaning of which is up to you. It usually indicates a situation where the criteria for being enabled or disabled are mixed. For example, many word processors have control bar buttons that indicate the current text format, such as a button with a B on it to indicate bold text. This button is unchecked when the current text format is not bold and checked when the format is bold. But if a block of text contains text, some of which is bold and some not, the button is placed in its indeterminate state.

A variation of toggling button gadgets is to enable or disable an exclusive button gadget. Exclusive button gadgets work just like radio buttons. In a group of exclusive button gadgets only one button gadget can be on at a time. Enabling another button gadget in the group disables the previously enabled button gadget.

To toggle a command item,

1.	Add the command-enabling handler function and response table macro to your window class (as shown in Handling Command-Enabling Messages).

2.	Define the handler function.

3.	Inside the handler function, call the SetCheck member function of the command-enabling object passed into the handler function. SetCheck takes a single int parameter. Call SetCheck with one of the enumerated values defined in TCommandEnabler: Checked, Unchecked, or Indeterminate.

Note: If you are turning on a check mark for a menu item and setting the text for that menu item in the same function, you must call SetText before you call SetCheck. Reversing this order removes the check mark.

A common use for toggling command items is to let the user of your application specify if some feature should be active. For example, suppose your application provides both a menu item and a control bar button to access the CmFileSave function. Many applications provide fly-over hints, short descriptions that appear in the status bar when the pointer moves over a menu item or button gadget. You might want to let the user turn these hints off. To provide this option to the user, you can

1.	Add a new command identifier to your application, such as CM_TOGGLEHINTS.

2.	Add a new menu, perhaps named Options, with the menu item Fly-over Hints.

3.	Optionally add a new button to your button bar.

4.	Add a function to handle the CM_TOGGLEHINTS event and actually turn the hints on and off.

5.	Add a command-enabling function to check and uncheck the command items.

The code would look something like this:

class TMyDecFrame : public TDecoratedFrame

{

  public:

    TMyDecFrame(TWindow *parent = 0, char *title = 0, TWindow* client)

      : TDecoratedFrame(parent, title, client), hintMode (true) {}

    // Cb must be set by the application object

    // during the InitMainWindow function.

    TControlBar* Cb;

  protected:

    // hintMode indicates whether the hints are currently on or off.

    bool HintMode;

    // This is the function that actually turns the hints on and off.

    void CmToggleHints();

    // This is the command-enabling handler function.

    void CeToggleHints(TCommandEnabler& commandEnabler);

  DECLARE_RESPONSE_TABLE(TMyDecFrame);

};

DEFINE_RESPONSE_TABLE(TMyDecFrame)

  EV_COMMAND(CM_TOGGLEHINTS, CmToggleHints),

  EV_COMMAND_ENABLE(CM_TOGGLEHINTS, CeToggleHints),

END_RESPONSE_TABLE;

void

TMyDecFrame::CmToggleHints()

{

  if(HintMode)

    Cb->SetHintMode(TGadgetWindow::EnterHints);

  else

    Cb->SetHintMode(TGadgetWindow::NoHints);

  HintMode = !HintMode;

}

void

TMyDecFrame::CeToggleHints(TCommandEnabler& ce)

{

  ce.SetChecked(HintMode);

}

The control bar is set up by the application object in its InitMainWindow function. (The code for this is not shown here.) For a working example of command item toggling, see the example EXAMPLES\OWL\OWLAPPS\MDIFILE.


See Also

Application and Module Objects Overview

Changing Menu Item Text

Enabling and Disabling Command Items

Gadget and Gadget Window Objects

Handling Command-Enabling Messages

TCommandEnabler class


ObjectWindows Exception Handling

ObjectWindows provides a robust exception-handling mechanism for dealing with exceptional situations. An exceptional situation is any situation that falls outside your application's normal operating parameters. It can be something as innocuous as an unexpected user response or something as serious as an invalid handle or memory allocation failure. Exception handling provides a clean, efficient way to deal with these and other conditions.

You should be thoroughly familiar with C++ exception handling before reading this material.

The following topics describe ObjectWindows exception-handling encapsulation:

 	ObjectWindows Exception Hierarchy

 	Working with TXBase

 	Working with TXOwl

 	Specialized ObjectWindows Exception Classes

 	ObjectWindows Exception-Handling Macros


ObjectWindows Exception Hierarchy

ObjectWindows provides a number of classes that can be thrown as exceptions. Based on the TXBase and TXOwl classes, these exception classes can inform the user of the existing exceptional state, prompt the user for a course of action, create new exception objects, throw exceptions, and so on.

There are four exception classes that are implemented as independent classes:

 	TXBase is the base class for all ObjectWindows and exception classes. It is derived from the xmsg class.

 	TXOwl, derived from TXBase, is the base class for the ObjectWindows exception classes.

 	TXCompatibility describes exceptions that occur when TModule::Status has a non-zero value, providing backwards compatibility between the ObjectWindows 1.0 method of detecting exceptional situations and the ObjectWindows 2.x exception hierarchy. TXCompatibility maps the value of TModule::Status  to a resource string identifier.

 	TXOutOfMemory describes an exception that occurs when an attempt to allocate memory space for an object fails. This is analogous to the xalloc object thrown when new fails to properly allocate memory.

Two other classes, TXOle and TXAuto, are derived from TXBase. These classes provide exception handling for the classes.


Working with TXBase

As the base class for the ObjectWindows exception classes, TXBase provides the basic interface for working with ObjectWindows exceptions. TXBase can perform a number of functions, like

 Constructing itself, initializing its base xmsg object

 Cloning itself, making a copy of the exception object

 Throwing itself as an exception object


Constructing and Destroying TXBase

TXBase provides two public constructors:

TXBase(const string& msg);

TXBase(const TXBase& src);

The first constructor initializes the xmsg base class with the value of the string parameter, calling the xmsg constructor that takes a string parameter. The second creates a new object that is a copy of the TXBase object passed in as a parameter.

Both constructors increment the TXBase data member InstanceCount, a static int (causing there to be only a single instance of the member no matter how many actual TXBase or TXBase-derived objects exist in the application). The TXBase destructor decrements InstanceCount. The destructor is declared virtual to allow easy overriding of the destructor.

Because each new TXBase or TXBase-derived object increments InstanceCount, and each deleted TXBase or TXBase-derived object decrements InstanceCount, the value of InstanceCount reflects the total number of TXBase and TXBase-derived objects existing in the application at the time. To access InstanceCount from outside a TXBase or TXBase-derived class, qualify the name InstanceCount with a TXBase:: scope qualifier.


Cloning Exception Objects

SeeAlso

TXBase contains a function called Clone. This function takes no parameters and returns a TXBase*. Clone creates a copy of the current exception object by allocating a new TXBase object with new and passing a dereferenced this pointer to the copy constructor.

TXBase*

TXBase::Clone()

{

  return new TXBase(*this);

}

It is important to note that any classes derived from TXBase must override Clone to use the proper constructor. For example, the TXOwl class, which is derived from TXBase, implements the Clone function like this:

TXOwl*

TXOwl::Clone()

{

  return new TXOwl(*this);

}


SeeAlso

Working with TXOwl


Throwing TXBase Exceptions

After you have created or cloned a TXBase object, you can throw the object in one of three ways:

 	Use the throw keyword followed by the object name, as follows:

TXBase xobj("Some exception...");

Throw xobj;

 	Use the ObjectWindows THROW macro, which corresponds to the C++ keyword throw. The previous example would look like this:

TXBase xobj("Some exception...");

Throw xobj;

 Call the exception object's Throw function, as follows:

TXBase xobj("Some exception...");

xobj.Throw();

This last method provides strict type safety when you throw the exception. It also provides a polymorphic interface when throwing the exception, allowing the function that catches a TXBase-derived exception object to treat the object as a TXBase object, regardless of what it actually is.


Working with TXOwl

SeeAlso

As the base class for the ObjectWindows exception classes, TXOwl provides the basic interface for working with ObjectWindows exceptions. In addition to the functionality provided in TXBase, TXOwl can perform other functions, such as

 Constructing itself (initializing its base objects)

 Cloning itself (making a copy of the exception object)

TXOwl can also pass unhandled exceptions to the application object's Error function or to the global exception handler HandleGlobalException.


SeeAlso

Working with TXBase


Constructing and Destroying TXOwl

TXOwl has two constructors to provide flexibility in passing the exception message string:

TXOwl(const string& str, unsigned resId = 0);

TXOwl(unsigned resId, TModule* module = ::Module);

The first constructor initializes the TXBase base object with the value of the str parameter. resId is used as an error number.

The second constructor loads the string resource identified by resId and uses the string to initialize TXBase. The TModule* identifies the module from which the resource should be loaded. It defaults to the global current module pointer Module, meaning that the resource should be loaded from the current module or application.

The TXOwl destructor has no default functionality other than that inherited from TXBase.


Cloning TXOwl and TXOwl-Derived Exception Objects

TXOwl contains a Clone function. This function takes no parameters and returns a TXOwl*. Clone creates a copy of the current exception object by allocating a new TXOwl object with new and passing a dereferenced this pointer to the automatic copy constructor. The function is defined as follows:

TXOwl* TXOwl::Clone()

{

  return new TXOwl(*this);

}

It is important to note that any classes derived from TXOwl must override this function to use the proper constructor. for example, the TXOutOfMemory class, which is derived from TXOwl, implements the Clone function like this:

TXOwl* TXOutOfMemory::Clone()

{

  return new TXOutOfMemory(*this);

}

Note that the return type is still TXOwl*. With this return type, ObjectWindows exception-handling functions can treat any exception object as a TXOwl object.

Also note that the return type for TXOwl::Clone differs from TXBase::Clone. TXBase provides the basic functionality for both the ObjectWindows and the ObjectComponents exception classes, but TXOwl provides the basic interface for the ObjectWindows exception classes alone.


Specialized ObjectWindows Exception Classes

A number of regular ObjectWindows classes implement specialized exception classes, all of which are based on TXOwl, that are defined within the implementing class definition to provide name scoping. The following table describes these classes, along with the unique functionality of each class.

Parent Class	Exception Class	Description

TApplication	TXInvalidMainWindow	Initializes the exception message with the IDS_INVALIDMAINWINDOW string resource. This object is thrown when the MainWindow member of TApplication contains either an invalid pointer or a pointer to an invalid window.

TModule	TXInvalidModule	Initializes the exception message with the IDS_INVALIDMODULE string resource. This exception is thrown in the TModule constructor when the module's HInstance is invalid.

TWindow	TXWindow	Initializes the exception message with the window title and with a string resource passed to the TXWindow constructor. This exception is thrown in situations where an error relating to a window object has occurred.

TMenu	TXMenu	Initializes the exception message with a string resource passed to the TXMenu constructor, by default, the IDS_GDIFAILURE string resource. This exception is thrown when a menu object's handle is invalid.

TValidator	TXValidator	Initializes the exception message with a string resource passed to the TXValidator constructor. By default this is the IDS_VALIDATORSYNTAX string resource. This exception is thrown when a validator expression is corrupt or invalid.

TGdiBase	TXGdi	Initializes the exception message with a string resource passed to the TXGdi constructor, along with the GDI object handle. By default, the string resource is IDS_GDIFAILURE and the GDI object handle is 0 (zero). This exception is thrown in many situations when an error relating to a graphics object has occurred.

TPrinter	TXPrinter	Initializes the exception message with a string resource passed to the TXPrinter constructor. By default this is the IDS_PRINTERERROR string resource. This exception is thrown when the printer's device context is invalid.


ObjectWindows Exception-Handling Macros

ObjectWindows provides a number of macros for implementing exception handling. Although you can use the standard C++ keywords such as try, catch, throw, and so on, the ObjectWindows macros enable you to turn exception handling on and off simply by defining or not defining a single symbol. The macros provided are

TRY

THROW(x)

THROWX(x)

RETHROW

CATCH(x)

See the following topics for more information:

Turning ObjectWindows Exceptions On and Off

ObjectWindows Exception Macro Expansion


Turning ObjectWindows Exceptions on and Off

The symbol that switches exception handling on and off in ObjectWindows applications is NO_CPP_EXCEPTIONS. The value assigned to NO_CPP_EXCEPTIONS does not matter: What does matter is whether it is defined.

If it is not defined, the exception-handling macros expand to implement exception handling.

If it is defined, the macros provide only the barest functionality by aborting the application when an exception is thrown.

The precise behaviors of the macros when exception handling is switched on and off is described later.

There are a number of different ways to define NO_CPP_EXCEPTIONS. The following list makes a few suggestions:

 	You can specify the -DNO_CPP_EXCEPTIONS option on the MAKE command line to define the macro with no specific value.

 	You can define the symbol using the method provided in your graphical development environment, such as the Borland C++ IDE.

 	You can define NO_CPP_EXCEPTIONS in your source code. This method might be less desirable than the previous ones because modifying the source code modifies the time stamp on the file. If you're using MAKE or some other dependency-checking program to build your application, you might or might not want the time stamp to change.


ObjectWindows Exception Macro Expansion

The exception-handling macros in ObjectWindows behave differently depending on whether NO_CPP_EXCEPTIONS is defined. The following table explains how each macro is expanded depending on the state of NO_CPP_EXCEPTIONS:

Macro	NO_CPP_EXCEPTIONS	NO_CPP_EXCEPTIONS

defined	not defined

TRY	Expands to nothing, removing 	Expands to try, allowing the code in

the try statement.	the try block to be tested for thrown exceptions.

THROW(x)	Calls the abort function.	Expands to throw(x), throwing the x object if the exceptional conditions are met.

THROWX(x)	Calls the abort function.	Expands to x.Throw(), calling object x's Throw function. This macro should only be used with TXBase-derived classes.

RETHROW	Expands to nothing, removing 	Expands to throw. This macro

the throw statement.	should be used only inside catch (or CATCH) clauses to rethrow the caught exception.

CATCH(x)	Expands to nothing, removing	Expands to catch x, catching

the catch statement.	exceptions thrown with objects of type x.


Window Objects Overview (ObjectWindows)

See Also

Window objects are high-level interface objects with facilities to make dealing with windows and their children and controls easier. ObjectWindows provides several different types of window objects:

Layout windows

Frame windows

Decorated frame windows

MDI windows

You can create, display, and fill window objects. To do so, you'll need to perform the following tasks:

Constructing window objects

Setting creation attributes

Creating window interface elements


See Also

Gadget and Gadget Window Objects Overview (ObjectWindows)


Constructing Window Objects (ObjectWindows)

See Also

Window objects represent interface elements. The object is connected to the element through a handle stored in the object's HWindow data member. HWindow is inherited from TWindow. When you construct a window object, its interface element does not yet exist. You must create it in a separate step. TWindow also has a constructor you can use in a DLL to create a window object for an interface element that already exists.

Several ObjectWindows classes use TWindow or TFrameWindow as a virtual base. These classes include TDialog, TMDIFrame, TTinyCaption, TMDIChild, TDecoratedFrame, TLayoutWindow, TClipboardViewer, and TFrameWindow. In C++, virtual base classes are constructed first, which means that the derived class's constructor cannot specify default arguments for the base class constructor. There are two ways to handle this problem:

Explicitly construct your immediate base class or classes and any virtual base classes when you construct your derived class.

Use the virtual base's default constructor. Both TWindow and TFrameWindow have default constructors. Each also has an Init function that lets you specify parameters for the base class. Call this Init function in the constructor of your derived class to set any parameters you need in the base class.

Here are some examples of how to construct a window object using these methods:

class TMyWin : public TFrameWindow

{

  public:

    // This constructor calls the base class constructors

    TMyWin(TWindow *parent, char *title)

      : TFrameWindow(parent, title),

        TWindow(parent, title) {}

}

TMyWin *myWin = new TMyWin(GetMainWindow(), "Child window");

class TNewWin : virtual public TWindow

{

  public:

    TNewWin(TWindow *parent, char *title);

}

TNewWin::TNewWin(TWindow *parent, char *title)

{

  // This constructor uses the default base class

  // constructors and calls Init.

  Init(parent, title, IDL_DEFAULT);

};

TNewWin *newWin = new TMyWin(GetMainWindow(), "Child window");


See Also

Creating Window Interface Elements (ObjectWindows)

Setting Creation Attributes (ObjectWindows)


Setting Creation Attributes (ObjectWindows)

See Also

A typical Windows application has many different types of windows: overlapped or pop-up, bordered, scrollable, and captioned, to name a few. The different types are selected with style attributes. Style attributes, as well as a window's title, are set during a window object's initialization and are used during the interface element's creation.

A window object's creation attributes, such as style and title, are stored in the object's Attr member, a TWindowAttr structure. The following table shows TWindowAttr's members:

Member	Type	Description

Style	uint32	Style constant.

ExStyle	uint32	Extended style constant.

X	int	The horizontal screen coordinate of the window's upper-left corner.

Y	int	The vertical screen coordinate of the window's upper-left corner.

W	int	The window's initial width in screen coordinates.

H	int	The window's initial height in screen coordinates.

Menu	TResId	ID of the window's menu resource. Do not try to directly assign a menu identifier to Attr.Menu! Use the AssignMenu function instead.

Id	int	Child window ID for communicating between a control and its parent. Id should be unique for all child windows of the same parent. If the control is defined in a resource, its Id should be the same as the resource ID. A window should never have both Menu and Id set, since these members actually occupy the same in the window's HWND structure.

Param	char far *	Used by TMDIClient to hold information about the MDI frame and child windows.

AccelTable	TResId	ID of the window's accelerator table resource.


See Also

Constructing Window Objects (ObjectWindows)

Creating Window Interface Elements (ObjectWindows)

Overriding Default Attributes (ObjectWindows)


Overriding Default Attributes (ObjectWindows)

See Also

The following table shows some default values you might want to override for Attr members:

Note:	A value of 0 means to use the Windows default value.

Attr member	Default value

Style	WS_CHILD | WS_VISIBLE

ExStyle	0

X	0

Y	0

W	0

H	0

Menu	0

Id	0

Param	0

AccelTable	0

You can override those defaults in a derived window class's constructor by changing the values in the Attr structure. For example:

TTestWindow::TTestWindow(TWindow* parent, const char* title)

  : TFrameWindow(parent, title), TWindow(parent, title)

{

  Attr.Style &= (WS_SYSMENU | WS_MAXIMIZEBOX);

  Attr.Style |= WS_MINIMIZEBOX;

  Attr.X = 100;

  Attr.Y = 100;

  Attr.W = 415;

  Attr.H = 355;

}

Child-window Attributes

You can set the attributes of a child window in the child window's constructor or in the code that creates the child window. When you change the attributes in the parent window object's constructor, you need to use a pointer to the child window object to get access to its Attr member.

TTestWindow::TTestWindow(TWindow* parent, const char* title)

  : TWindow(parent, title)

{

  TWindow helpWindow(this, "Help System");

  helpWindow.Attr.Style |= WS_POPUPWINDOW | WS_CAPTION;

  helpWindow.Attr.X = 100;

  helpWindow.Attr.Y = 100;

  helpWindow.Attr.W = 300;

  helpWindow.Attr.H = 300;

  helpWindow.SetCursor(0, IDC_HAND);

}


See Also

Setting Creation Attributes (ObjectWindows)


Creating Window Interface Elements (ObjectWindows)

See Also

After you have constructed a window object, you need to tell Windows to create the associated interface element. Do this by calling the object's Create member function,

window.Create();

Create does the following things:

Creates the interface element

Sets HWindow to the handle of the interface element

Sets members of Attr to the actual state of the interface element (Style, ExStyle, X, Y, H, W)

Calls SetupWindow

An application's main window is automatically created by TApplication::InitInstance. You do not need to call Create yourself to create the main window.

C++ exceptions can be thrown while creating a window object's interface element. You should therefore enclose calls to Create within a try/catch block to handle any memory or resource problems your application might encounter. Create throws a TXWindow exception initialized with an IDS_WINDOWCREATEFAIL when the window cannot be created or an IDS_CLASSREGISTERFAIL when the window class cannot be registered. SetupWindow throws a TXWindow exception initialized with an IDS_CHILDCREATEFAIL when a child window in the window cannot be created. These exceptions are usually caused by insufficient memory or other resources.

Example

Here is an example of using exceptions to catch an error while creating a window object:

try

{

  TWindow* window = new TMyWindow(this);

  window->Create();

}

catch(TXOwl& exp)

{

  MessageBox(exp.why.c_str(), "Window creation error");

  throw(exp);

}


See Also

Constructing Window Objects (ObjectWindows)

ObjectWindows Exception Handling

Overriding Default Attributes (ObjectWindows)

Setting Creation Attributes (ObjectWindows)


Layout Windows (ObjectWindows)

See Also

Layout windows are encapsulated in the class TLayoutWindow, which is derived from TWindow. Along with TFrameWindow, TLayoutWindow provides the basis for decorated frame windows and their ability to arrange decorations in the frame area.

Layout windows are so named because they can lay out child windows in the layout window's client area. The children's locations are determined relative to the layout window or another child window (known as a sibling). The location of a child window depends on that window's layout metrics, which consist of a number of rules that describe the window's X and Y coordinates, its height, and its width. These rules are usually based on a sibling window's coordinates and, ultimately, on the size and arrangement of the layout window.

Layout metrics for a child window are contained in a class called TLayoutMetrics. A layout metrics object consists of a number of layout constraints. Each layout constraint describes a rule for finding a particular dimension, such as the X coordinate or the width of the window. It takes four layout constraints to fully describe a layout metrics object. Layout constraints are contained in a structure named TLayoutConstraint, but you usually use one of the TLayoutConstraint-derived classes, such as TEdgeConstraint, TEdgeOrWidthConstraint, or TEdgeOrHeightConstraint.


See Also

Defining Constraining Relationships (ObjectWindows)

Defining Constraints (ObjectWindows)

Layout Constraints (ObjectWindows)

Using Layout Windows (ObjectWindows)


Layout Constraints (ObjectWindows)

See Also

Layout constraints specify a relationship between an edge or dimension of one window and an edge or dimension of a sibling window or the parent layout window. This relationship can be quite flexible. For example, you can set the width of a window to be a percentage of the width of the parent window, so that whenever the parent is resized, the child window is resized to take up the same relative window area. You can also set the left edge of a window to be the same as the right edge of another child, so that when the windows are moved around, they are tied together. You can even constrain a window to occupy an absolute size and position in the client area.

The three types of constraints most often used are TEdgeConstraint, TEdgeOrWidthConstraint, and TEdgeOrHeightConstraint. These structures constitute the full set of constraints used in the TLayoutMetrics. TEdgeOrWidthConstraint and TEdgeOrHeightConstraint are derived from TEdgeConstraint. From the outside, these three objects look almost the same. Discussions of TEdgeConstraint refer to all three objectsTEdgeConstraint, TEdgeOrWidthConstraint, and TEdgeOrHeightConstraintunless the other two classes are explicitly excluded from a statement.


See Also

Defining Constraining Relationships (ObjectWindows)

Defining Constraints (ObjectWindows)

Using Layout Windows (ObjectWindows)


Defining Constraints (ObjectWindows)

See Also

The most basic way to define a constraining relationship (that is, set up a relationship between an edge or size of one window and an edge or size of another window) is to use the Set function. The Set function is defined in the TEdgeConstraint class and subsequently inherited by TEdgeOrWidthConstraint and TEdgeOrHeightConstraint.

Here is the Set function declaration:

void Set(TEdge edge, TRelationship rel,

         TWindow* otherWin, TEdge otherEdge,

         int value = 0);

In this declaration,

edge specifies which part of the window you are constraining and uses the enum TEdge, which has five possible values:

lmLeft specifies the left edge of the window.

lmTop specifies the top edge of the window.

lmRight specifies the right edge of the window.

lmBottom specifies the bottom edge of the window.

lmCenter specifies the center of the window. The object that owns the constraint, such as TLayoutMetrics, determines whether the center of the window is the vertical center or the horizontal center.

You can also specify the window's width or height as a constraint, but only with TEdgeOrWidthConstraint and TEdgeOrHeightConstraint. Use the enum TWidthHeight, which has two possible values:

lmWidth specifies that the width of the window should be constrained.

lmHeight specifies that the height of the window should be constrained.

rel specifies the relationship between the two edges, as follows:

rel	Relationship

lmAsIs	This dimension is constrained to its current value.

lmPercentOf	This dimension is constrained to a percentage of the constraining edge's size. This is usually used with a constraining width or height.

lmAbove	This dimension is constrained to a certain distance above its constraining edge.

lmLeftOf	This dimension is constrained to a certain distance to the left of its constraining edge.

lmBelow	This dimension is constrained to a certain distance below its constraining edge.

lmRightOf	This dimension is constrained to a certain distance to the right of its constraining edge.

lmSameAs	This dimension is constrained to the same value as its constraining edge.

lmAbsolute	This dimension is constrained to an absolute coordinate or size.

otherWin specifies the window with which you are constraining your child window. You must use the value lmParent when specifying the parent window. Otherwise, pass a pointer to the TWindow or TWindow-derived object containing the other window.

otherEdge specifies the particular edge of otherWin with which you are constraining your child window. otherEdge can have any of the values allowed for edge.

value means different things, depending on the value of rel:

rel	Meaning of value

lmAsIs	No meaning. Should be set to 0.

lmPercentOf	What percent of the constraining measure the constrained measure should be.

lmAbove	How many units above the constraining edge the constrained edge should be.

lmLeftOf	How many units to the left of the constraining edge the constrained edge should be.

lmBelow	How many units below the constraining edge the constrained edge should be.

lmRightOf	How many units to the left of the constraining edge the constrained edge should be.

lmSameAs	No meaning. Should be set to 0.

lmAbsolute	The absolute measure for the constrained edge, as follows:

When edge is lmLeft, lmRight, or sometimes lmCenter, value is the X coordinate for the edge.

When edge is lmTop, lmBottom, or sometimes lmCenter, value is the Y coordinate for the edge.

When edge is lmWidth or lmHeight, edge represents the size of the constraint.

The owning object determines whether lmCenter represents an X or Y coordinate.

The meaning of value is also dependent on the value of Units, a TMeasurementUnits member of TLayoutConstraint. TMeasurementUnits is an enum that describes the type of unit represented by value. Units can be either lmPixels or lmLayoutUnits. lmPixels indicates that value is meant to represent an absolute number of physical pixels. lmLayoutUnits indicates that value is meant to represent a number of logical units. These layout units are based on the size of the current font of the layout window.

TEdgeConstraint also contains a number of functions that you can use to set up predefined relationships. These correspond closely to the relationships you can specify in the Set function. In fact, these functions call Set to define the constraining relationship. You can use these functions to set up a majority of the constraint relationships you define.

The following four functions work in a similar way:

void LeftOf	(TWindow* sibling, int margin = 0);

void RightOf	(TWindow* sibling, int margin = 0);

void Above	(TWindow* sibling, int margin = 0);

void Below	(TWindow* sibling, int margin = 0);

Each of these functions places the child window in a certain relationship with the constraining window sibling. The edges are predefined, with the constrained edge being the opposite of the function name and the constraining edge being the same as the function name.

For example, the LeftOf function places the child window to the left of sibling. This means the constrained edge of the child window is lmRight and the constraining edge of sibling is lmLeft.

You can set an edge of your child window to an absolute value with the Absolute function,

void Absolute(TEdge edge, int value);

edge indicates which edge you want to constrain, and value has the same value as when used in Set with the lmAbsolute relationship.

There are two other shortcut functions you can use,

void SameAs(TWindow* otherWin, TEdge edge);

void PercentOf(TWindow* otherWin, TEdge edge, int percent);

These two use the same edge for the constrained window and the constraining window. For example, if you specify lmLeft for edge, the left edge of your child window is constrained to the left edge of otherWin.


See Also

Defining Constraining Relationships (ObjectWindows)


Defining Constraining Relationships (ObjectWindows)

See Also

A single layout constraint is not enough to lay out a window. For example, specifying that one window must be 10 pixels below another window does not tell you anything about the width or height of the window, the location of the left or right borders, or the location of the bottom border. It only tells you that one edge is located 10 pixels below another window.

A combination of layout constraints can fully define a window's location (though there are some exceptions). The class TLayoutMetrics uses four layout constraint structures--two TEdgeConstraint objects named X and Y, a TEdgeOrWidthConstraint named Width, and a TEdgeOrHeightConstraint named Height.

TLayoutMetrics is a fairly simple class. The constructor takes no parameters. The only thing it does is to set up each layout constraint member. For each layout constraint, the constructor

Zeroes out the value for the constraining window.

Sets the constraint's relationship to lmAsIs.

Sets units to lmLayoutUnits.

Sets the value to 0.

The only difference is with MyEdge, which indicates the edge of the window this constraint applies to. X is set to lmLeft, Y is set to lmTop, Width is set to lmWidth, and Height is set to lmHeight.

Once you have constructed a TLayoutMetrics object, you need to set the layout constraints for the window you want to lay out. You can use the functions described in Defining Constraints (ObjectWindows) for setting each layout constraint.

X, Y, Width, and Height Labels

It is important to realize that the labels X, Y, Width, and Height are more labels of convenience than strict rules on how the constraints should be used. X can represent the X coordinate of the left edge, the right edge, or the center. You can combine this with the Width constraintwhich can be lmCenter, lmRight, or lmWidthto completely define the window's X-axis location and width. Using all the edge constraints is easy and is useful in situations where tiling is performed.

The simplest way is to assign an X coordinate to X and a width to width. But you could also set the edge for X to lmCenter and the edge for Width to lmRight. So Width does not really represent a width, but the X-coordinate of the window's right edge. If you know the X-coordinate of the right edge and the center, it's easy to calculate the X-coordinate of the left edge.

Indeterminate Constraints

You must be careful about how you specify your layout constraints. The constraints available in the TLayoutMetrics class give you the ability to fully describe a window. But they do not guarantee that the constraints you use fully describe a window. In cases where the constraints do not fully describe a window, the most likely result is an application crash.

Example

To better understand how constraints work together to describe a window, try building and running the example application LAYOUT in the directory EXAMPLES\OWL\OWLAPI\LAYOUT. This application has a number of child windows in a layout window. A dialog box you can access from the menu lets you change the constraints of each of the windows and then see the results as the windows are laid out. Be careful, though. If you specify a set of layout constraints that does not fully describe a window, the application will probably crash, or, if diagnostics are on, a check will occur.


See Also

Defining Constraints (ObjectWindows)


Using Layout Windows (ObjectWindows)

See Also

Once you've set up layout constraints, you are ready to create a layout window in which you can lay out the children. Here's the constructor for TLayoutWindow:

TLayoutWindow(TWindow* parent,

              const char far* title = 0,

              TModule* module = 0);

In this constructor,

parent is the layout window's parent window.

title is the layout window's title. This parameter defaults to a null string.

module is passed to the TWindow base class constructor as the TModule parameter for that constructor. This parameter defaults to 0.

After the layout window is constructed and displayed, there are a number of functions you can call:

The Layout function returns void and takes no parameters. This function tells the layout window to look at all its child windows and lay them out again. You can call this function to force the window to recalculate the boundaries and locations of each child window. You usually want to call Layout after you have moved a child window, resized the layout window, or done anything else that could affect the constraints of the child windows.

Note:	TLayoutWindow overrides the TWindow version of EvSize to call Layout automatically whenever a WM_SIZE event is caught. If you override this function yourself, you should be sure either to call the base class version of the function or call Layout in your derived version.

SetChildLayoutMetrics returns void and takes a TWindow & and a TLayoutMetrics & as parameters. Use this function to associate a set of constraints contained in a TLayoutMetrics object with a child window. Here is an example of creating a TLayoutMetrics object and associating it with a child window:

TMyLayoutWindow::TMyLayoutWindow(TWindow* parent, char far* title)

  : TLayoutWindow(parent, title)

{

  TWindow MyChildWindow(this);

  TLayoutMetrics layoutMetrics;

  layoutMetrics.X.Absolute(lmLeft, 10);

  layoutMetrics.Y.Absolute(lmTop, 10);

  layoutMetrics.Width.PercentOf(lmParent, lmWidth, 60);

  layoutMetrics.Height.PercentOf(lmParent, lmHeight, 60);

  SetChildLayoutMetrics(MyChildWindow, layoutMetrics);

}

Note:	The child window does not need any special functionality to be associated with a layout metrics object. The association is handled entirely by the layout window itself. The child window does not have to know anything about the relationship.

GetChildLayoutMetrics returns a bool and takes a TWindow & and a TLayoutMetrics & as parameters. This function looks up the child window that is represented by the TWindow &. It then places the current layout metrics associated with that child window into the TLayoutMetrics object passed in. If GetChildLayoutMetrics does not find a child window that equals the window object passed in, it returns false.

RemoveChildLayoutMetrics returns a bool and takes a TWindow & for a parameter. This function looks up the child window that represented by the TWindow &. It then removes the child window and its associated layout metrics from the layout window's child list. If RemoveChildLayoutMetrics does not find a child window that equals the window object passed in, it returns false.

You must provide layout metrics for all child windows of a layout window. The layout window assumes that all its children have an associated layout metrics object. Removing a child window from a layout window or deleting the child window object automatically removes the associated layout metrics object.


See Also

Layout Constraints (ObjectWindows)


Frame Windows (ObjectWindows)

Frame windows (objects of class TFrameWindow) are specialized windows that support a client window. Frame windows are the basis for MDI and SDI frame windows, MDI child windows, and, along with TLayoutWindow, decorated frame windows.

Frame windows have an important role in ObjectWindows development: They manage application-wide tasks like menus and tool bars. Client windows within the frame can be specialized to perform a single task. Changes you make to the frame window (for example, adding tool bars and status bars) do not affect the client windows.

To take advantage of Frame windows, you need to be able to

Construct frame windows

Modify frame windows


Constructing Frame Window Objects (ObjectWindows)

See Also

You can construct a frame window object using one of the two TFrameWindow constructors. These two constructors let you:

Construct new frame window objects along with new interface elements

Construct a frame window alias to connect a new frame window object to an existing interface element.


See Also

Modifying Frame Windows (ObjectWindows)


Constructing New Frame Windows (ObjectWindows)
Constructing New Frame Windows

See Also

The following TFrameWindow constructor is used to create an entirely new frame window object:

TFrameWindow(TWindow *parent,

             const char far *title = 0,

             TWindow *clientWnd = 0,

             bool shrinkToClient = false,

             TModule *module = 0);

Parameter	Explanation

parent	The window's parent window object. Use zero if the window you're creating is the main window (which does not have a parent window object). Otherwise, use a pointer to the parent window object. This is the only parameter that you must provide.

title	The window title, the string that appears in the caption bar of the window. If you do not specify anything, no title is displayed in the title bar.

clientWnd	Lets you specify a client window for the frame window by passing a pointer to the client window object.. If you do not specify anything, by default the constructor gets a zero, meaning that there is no client window.

shrinkToClient	Lets you specify whether the frame window should shrink to fit the client window. If you do not specify anything, by default the constructor gets false, meaning that it should not fit the frame to the client window.

module	Passed to the base class constructor as the TModule parameter for that constructor. This parameter defaults to 0.

Example

Here are some examples of using this constructor:

void TMyApplication::InitMainWindow()

{

  // default is for no client window

  SetMainWindow(new TFrameWindow(0, "Main Window"));

}

void TMyApplication::InitMainWindow()

{

  // client window is TMyClientWindow

  SetMainWindow(new TFrameWindow(0, "Main window with client",

                                 new TMyClientWindow, true));

}


See Also

Constructing a Frame Window Alias (ObjectWindows)

Constructing Frame Window Objects (ObjectWindows)

Modifying Frame Windows (ObjectWindows)


Constructing a Frame Window Alias (ObjectWindows)
Constructing a Frame Window Alias

See Also

This TFrameWindow constructor is used to connect an existing interface element to a new TFrameWindow object. This object is known as an alias for the existing window.

TFrameWindow(HWND hWnd, TModule *module);

Parameter	Explanation

hWnd	The window handle of the existing interface element. This is the window the TFrameWindow object controls.

module	Passed to the base class constructor as the TModule parameter for that constructor. This parameter defaults to 0.

This version of the constructor is useful for creating window objects for existing windows. You can then manipulate any window as if it were an ObjectWindows-created window. This is useful in situations such as DLLs, when a non-ObjectWindows application calling into the DLL passes in an HWND. You can then construct a TFrameWindow alias for the HWND and call TFrameWindow member functions as you normally would.

Example

The following example shows how to construct a TFrameWindow for an existing interface element and use that window as the main window:

void TMyApplication::AddWindow(HWND hWnd)

{

  TFrameWindow* frame = new TFrameWindow(hWnd);

  TFrameWindow* tmp = SetMainWindow(frame);

  ShowWindow(GetMainWindow()->HWindow, SW_SHOW);

  tmp->ShutDownWindow();

}

When you use this constructor for TFrameWindow, it sets the flag wfAlias. You can tell whether a window element was constructed from its window object or whether it's actually an alias by calling the function IsFlagSet with the wfAlias flag. For example, suppose you do not know whether the function AddWindow in the last example has executed yet. If your main window is not an alias, AddWindow has not executed. If your main window is an alias, AddWindow has executed.

void TMyApplication::CheckAddExecute()

{

  if(GetMainWindow()->IsFlagSet(wfAlias))

   // MainWindow is an alias; AddWindow has executed

  else

   // MainWindow is not an alias; AddWindow has not executed

}


See Also

Constructing Frame Window Objects (ObjectWindows)

Constructing New Frame Windows (ObjectWindows)

Modifying Frame Windows (ObjectWindows)


Modifying Frame Windows (ObjectWindows)

See Also

Many frame window attributes can be set after the object has been constructed. You can change and query object attributes. TFrameWindow provides an additional set of functions for modifying frame windows:

Function	Explanation

AssignMenu	Typically used to set up a window's menu before the interface element has been created, such as in the InitMainWindow function or the window object's constructor or SetupWindow function.

SetMenu	Sets the window's menu handle to the HMENU parameter passed in.

SetMenuDescr	Sets the window's menu description to the TMenuDescr parameter passed in.

GetMenuDescr	Returns the current menu description.

MergeMenu	Merges the current menu description with the TMenuDescr parameter passed in.

RestoreMenu	Restores the window's menu from Attr.Menu.

SetIcon	Sets the icon in the module passed as the first parameter to the icon passed as a resource in the second parameter.


See Also

Constructing a Frame Window Alias (ObjectWindows)

Constructing Frame Window Objects (ObjectWindows)

Constructing New Frame Windows (ObjectWindows)


Decorated Frame Windows (ObjectWindows)

Decorated frame windows are encapsulated in TDecoratedFrame, which is derived from TFrameWindow and TLayoutWindow. Decorated frame windows provide all the functionality of frame windows and layout windows, but in addition provide:

Support for adding controls (known as decorations) to the frame of the window

Automatic adjustment of the child windows to accommodate the placement of decorations

To take advantage of decorated frame windows, you need to know how to

Construct decorated frame window objects

Add decorations to decorated frame windows


Constructing Decorated Frame Window Objects (ObjectWindows)

See Also

TDecoratedFrame has only one constructor,

TDecoratedFrame(TWindow* parent,

                const char far* title,

                TWindow* clientWnd,

                bool trackMenuSelection = false,

                TModule* module = 0);

Parameter	Explanation

parent	The window's parent window object. Use zero if the window you're creating is the main window (which does not have a parent window object). Otherwise use a pointer to the parent window object. This is the only parameter that you must provide.

title	The window title, which appears in the caption bar of the window. If you do not specify anything, no title is displayed in the title bar.

clientWnd	Lets you specify a pointer to a client window for the frame window. If you do not specify anything, by default the constructor gets a zero, meaning that there is no client window.

trackMenuSelection	Lets you specify whether menu commands should be tracked. When tracking is on, the window tries to pass a string to the window's status bar. The string passed has the same resource name as the currently selected menu choice. You should not turn on menu selection tracking unless you have a status bar in your window. If you do not specify anything, by default the constructor gets false, meaning that it should not track menu commands.

module	Passed to the base class constructor as the TModule parameter for that constructor. This parameter defaults to 0.


See Also

Adding Decorations To Decorated Frame Windows


Adding Decorations To Decorated Frame Windows (ObjectWindows)

See Also

TDecoratedFrame provides the ability to add decorations by using the Insert member function.

To use Insert, you must first construct a control to be inserted. Valid controls include control bars (TControlBar), status bars (TStatusBar), button gadgets (TButtonGadget), and any other control type based on TWindow.

After you have constructed the control, use Insert to insert the control into the decorated frame window. Insert takes two parameters, a reference to the control and a location specifier. TDecoratedFrame provides the enum TLocation, which lets you specify four possible values: Top, Bottom, Left, and Right.

Example

Suppose you want to construct a status bar to add to the bottom of your decorated frame window. The code would look something like this:

TStatusBar* sb = new TStatusBar(0, TGadget::Recessed,

                                TStatusBar::CapsLock |

                                TStatusBar::NumLock |

                                TStatusBar::Overtype);

TDecoratedFrame* frame = new TDecoratedFrame(0,

                                             "Decorated Frame",

                                             0,

                                             true);

frame->Insert(*sb, TDecoratedFrame::Bottom);


See Also

Constructing Decorated Frame Window Objects

Object Properties (ObjectWindows)

Window Properties (ObjectWindows)


MDI Windows (ObjectWindows)

See Also

Multiple document interface (MDI) windows are part of the MDI interface for managing multiple windows or views associated with a single application. A document is usually a file-specific task, such as editing a text file or working on a spreadsheet file.

MDI Applications

Certain components are present in every MDI application. Most evident is the main window, called the MDI frame window. Within the frame window's client area is the MDI client window, which holds child windows called MDI child windows. When using the Doc/View classes, the application can put views into MDI windows.

The MDI Window Menu

An MDI application usually has a menu item labeled Window that controls the MDI child windows. The Window menu usually has items like Tile, Cascade, Arrange, and Close All. The name of each open MDI child window is automatically added to the end of this menu, and the currently selected window is checked.

MDI Child Windows

MDI child windows have some characteristics of an overlapped window. An MDI child window can be maximized to the full size of its MDI client window or minimized to an icon that sits inside the client window. MDI child windows never appear outside their client or frame windows. Although MDI child windows cannot have menus attached to them, they can have a TMenuDescr that the frame window uses as a menu when that child is active. The caption of each MDI child window is often the name of the file associated with that window; this behavior is optional and under your control.

MDI in ObjectWindows

ObjectWindows defines classes for each type of MDI window:

TMDIFrame

TMDIClient

TMDIChild

In ObjectWindows, the MDI frame window owns the MDI client window, and the MDI client window owns each of the MDI child windows.

TMDIFrame's member functions manage the frame window and its menu. ObjectWindows first passes commands to the focus window and then to its parent, so the client window can process the frame window's menu commands. Because TMDIFrame does not have much specialized behavior, you rarely have to derive your own MDI frame window class; instead, just use an instance of TMDIFrame. Since TMDIChild is derived from TFrameWindow, it can be a frame window with a client window. Therefore, you can create specialized windows that either serve as client windows in a TMDIChild or are TMDIChild windows themselves. The preferred style is to use specialized clients with the standard TMDIChild class. The choice is yours and depends on your particular application.


See Also

Adding Behavior To an MDI Client Window (ObjectWindows)

Building an MDI Application (ObjectWindows)

Creating an MDI Frame Window (ObjectWindows)

Creating MDI Child Windows (ObjectWindows)


Building an MDI Application (ObjectWindows)

Follow these steps to building an MDI application in ObjectWindows:

1.	Create an MDI frame window

2.	Add behavior to an MDI client window

3.	Create MDI child windows

ObjectWindows' TMDIFrame, TMDIClient, and TMDIChild classes handle the MDI-specific behavior for you so you can concentrate on the application-specific behavior you want.


Creating an MDI Frame Window (ObjectWindows)

See Also

The MDI frame window is always an application's main window, so you construct it in the application object's InitMainWindow member function. MDI frame windows differ from other frame windows in the following ways:

Because an MDI frame is always a main window, it never has a parent. Therefore, TMDIFrame's constructor does not take a pointer to a parent window object as a parameter.

An MDI frame must have a menu, so TMDIFrame's constructor takes a menu resource identifier as a parameter. With non-MDI main frame windows, you would call AssignMenu to set the window's menu. TMDIFrame's constructor makes the call for you. Part of what AssignMenu does is search the menu for the child-window menu by searching for certain menu command IDs. If it finds a Window menu, new child window titles are automatically added to the bottom of the menu.

Example

A typical InitMainWindow for an MDI application would look like this:

void TMDIApp::InitMainWindow()

{

  SetMainWindow(new TMDIFrame("MDI App", ID_MENU,
  *new TMyMDIClient));

}

The example creates an MDI frame window titled "MDI App" with a menu from the ID_MENU resource. The ID_MENU menu should have a child-window menu. The MDI client window is created from the TMyMDIClient class.


See Also

Adding Behavior To an MDI Client Window (ObjectWindows)

Creating Child Windows (ObjectWindows)


Add Behavior To an MDI Client Window (ObjectWindows)
Adding Behavior To an MDI Client Window (ObjectWindows)

See Also

Because you usually use an instance of TMDIFrame as your MDI frame window, you need to add application-wide behavior to your MDI client window class. The frame window owns menus and tool bars but passes the commands they generate to the client window and to the application. A common message-response function would respond to the File|Open menu command to open another MDI child window.

Manipulating Child Windows

TMDIClient has several member functions for manipulating MDI child windows. Commands from an MDI application's child-window menu control the child windows. TMDIClient automatically responds to those commands and performs the appropriate action:

Action	Menu command ID	TMDIClient member function

Cascade	CM_CASCADECHILDREN	CmCascadeChildren

Tile	CM_TILECHILDREN	CmTileChildren

Tile Horizontally	CM_TILECHILDRENHORIZ	CmTileChildrenHoriz

Arrange Icons	CM_ARRANGEICONS	CmArrangeIcons

Close All	CM_CLOSECHILDREN	CmCloseChildren

Note: The header file owl\mdi.h includes owl\mdi.rh for your applications. owl\mdi.rh is a resource header file that defines the menu command IDs listed above. When you design your menus in your resource script, be sure to include owl\mdi.rh to get those IDs.

MDI child windows should not respond to any child-window menu commands. The MDI client window takes care of them.


See Also

Creating an MDI Frame Window (ObjectWindows)

Creating MDI Child Windows (ObjectWindows)


Creating MDI Child Windows (ObjectWindows)

See Also

There are two ways to create MDI child windows: automatically in TMDIClient::InitChild or manually elsewhere.

Automatic Child Window Creation

TMDIClient defines the CmCreateChild message response function to respond to the CM_CREATECHILD message. CmCreateChild is commonly used to respond to an MDI application's File|New menu command. CmCreateChild calls CreateChild, which calls InitChild to construct an MDI child window object, and finally calls the child object's Create member function to create the MDI child window interface element.

If your MDI application uses CM_CREATECHILD as the command ID to create new MDI child windows, then you should override InitChild in your MDI client window class to construct MDI child window objects whenever the user chooses that command, as follows:

TMDIChild* TMyMDIClient::InitChild()

{

  return new TMDIChild(*this, "MDI child window");

}

Since TMDIChild's constructor takes a reference to its parent window object and not a pointer, you need to dereference the this pointer.

Manual Child Window Creation

You do not have to construct MDI child window objects in InitChild. If you construct them elsewhere, however, you must create the interface element yourself:

void

TMyMDIClient::CmFileOpen()

{

  new TMDIChild(*this, "")->Create();

}


See Also

Adding Behavior To an MDI Client Window (ObjectWindows)

Creating an MDI Frame Window (ObjectWindows)


Menu Objects Overview (ObjectWindows)

ObjectWindows menu objects encapsulate menu resources and provide an interface for controlling and modifying the menu. Many applications use only a single menu assigned to the main window during its initialization. Other applications might require more complicated menu handling. ObjectWindows menu objects, encapsulated in the TMenu, TSystemMenu, TPopupMenu, and TMenuDescr classes, give you an easy way to create and manipulate menus, from basic functionality to complex menu merging.

When you work with menu objects, you can

Construct menu objects

Create menu groups in menu resources

Modify menu objects

Query menu objects

Use popup menu objects

Use system menu objects

Use menu objects with frame windows


Constructing Menu Objects (ObjectWindows)

See Also

TMenu has several constructors to create menu objects from existing windows or from menu resources. After the menu is created, you can add, delete, or modify it using TMenu member functions. The following table lists the constructors you can use to create menu objects:

TMenu constructor	Description

TMenu()	Creates an empty menu.

TMenu(HWND)	Creates a menu object representing the window's current menu.

TMenu(HMENU)	Creates a menu object from an already-loaded menu.

TMenu(LPCVOID*)	Creates a menu object from a menu template in memory.

TMenu(HINSTANCE, TResID)	Creates a menu object from a resource.


See Also

Modifying Menu Objects

Querying Menu Objects

Using Popup Menu Objects

Using System Menu Objects

Using menu objects with frame windows


Modifying Menu Objects (ObjectWindows)

See Also

After you create a menu object, you can use TMenu member functions to modify it. The table that follows lists the member functions you can call to modify menu objects.

After modifying the menu object, call the window object's DrawMenuBar member function to update the menu bar with the changes you have made.

TMenu member function	Description

Adding menu items

AppendMenu(uint, uint, const char*)	Adds a menu item to the end of the menu.

AppendMenu(uint, uint, const TBitmap&)	Adds a bitmap as a menu item at the end of the menu.

InsertMenu(uint, uint, uint, const char*)	Adds a menu item to the menu after the menu item of the given ID.

InsertMenu(uint, uint, uint, const TBitmap&)	Adds a bitmap as a menu item after the menu item of the given ID.

Modifying menu items

ModifyMenu(uint, uint, uint, const char*)	Changes the given menu item.

ModifyMenu(uint, uint, uint, const TBitmap&)	Changes the given menu item to a bitmap.

Enabling and disabling menu items

EnableMenuItem(uint, uint)	Enables or disables the given menu item.

Deleting and removing menu items

DeleteMenu(uint, uint)	Removes the menu item from the menu it is a part of. Deletes it if it is a popup menu.

RemoveMenu(uint, uint)	Removes the menu item from the menu but not from memory.

Checking menu items

CheckMenuItem(uint, uint)	Check or unchecks the menu item.

SetMenuItemBitmaps(uint, uint,	Specifies the bitmap to be displayed

   const TBitmap*, const TBitmap*)	when the given menu item is checked and unchecked.

Displaying popup menus

TrackPopupMenu(uint, int, int, int, HWND, TRect*)	Displays the menu as a popup menu at

TrackPopupMenu(uint, TPoint&, int, HWND, TRect*)	the given location on the specified

window.


See Also

Menu Objects Overview

TBitmap

TPoint

TRect


Querying Menu Objects (ObjectWindows)

See Also

TMenu has a number of member functions and member operators you can call to find out information about the menu object and its menu. You might need to call one of the query member functions before you call one of the modify member functions. For example, you need to call GetMenuCheckmarkDimensions before calling SetMenuItemBitmaps.

The following table lists the menu object query member functions:

Menu object query member function	Description

Querying the menu object as a whole

operator uint()	Returns the menu's handle as a uint.

operator HMENU()	Returns the menu's handle as an HMENU.

IsOK()	Checks if the menu is OK (has a valid handle).

GetMenuItemCount()	Returns the number of items in the menu.

GetMenuCheckMarkDimensions(TSize&)	Gets the size of the bitmap used to display the check mark on checked menu items.

Querying items in the menu

GetMenuItemID(int)	Returns the ID of the menu item at the specified position.

GetMenuState(uint, uint)	Returns the state flags of the specified menu item.

GetMenuString(uint, char*, int, uint)	Gets the text of the given menu item.

GetSubMenu(int)	Returns the handle of the menu at the given position.


See Also

Menu Objects Overview


Using System Menu Objects (ObjectWindows)

See Also

The TSystemMenu class lets you modify a window's system menu. TSystemMenu is derived from TMenu and differs from it only in its constructor, which takes a window handle and a bool flag. If the flag is true, the current system menu is deleted and a menu object representing the unmodified menu that is put in its place is created. If the flag is false, the menu object represents the current system menu. By default this flag is false.

You can use all the member functions inherited from TMenu to manipulate the system menu.

Example

The following example shows how to add an About... menu choice to the system menu:

void TSysMenuFrame::SetupWindow()

{

  TFrameWindow::SetupWindow();

  // Append About menu item to system menu.

  TSystemMenu sysMenu(HWindow);

  sysMenu.AppendMenu(MF_Separator, 0, (LPSTR)0);

  sysMenu.AppendMenu(MF_STRING, CM_ABOUT, "&About...");

}

Notice that the system menu is modified in the SetupWindow function of the window object. The system menu should be modified before the window is created. It is usually easiest to do this simply by overriding the base window class's SetupWindow function.


See Also

Menu Objects Overview (ObjectWindows)


Using Popup Menu Objects (ObjectWindows)

See Also

You can use TPopupMenu to create a popup menu that you can add to an existing menu structure or pop up anywhere in a window. Like TSystemMenu, TPopupMenu is derived from TMenu and differs from it only in its constructor, which creates an empty popup menu. You can then add whatever menu items you like by using the AppendMenu function.

After you have created a popup menu, you can use TrackPopupMenu to display it as a free-floating menu. TrackPopupMenu creates a pop-up menu at a particular location in your window. There are two forms of this function:

bool TrackPopupMenu(unit flags, int x, int y, int rsvd,
  HWND wnd, TRect* rect = 0)

bool TrackPopupMenu(unit flags, TPoint& point, int rsvd,
  HWND wnd, TRect* rect = 0)

The following table describes the parameters:

Parameter	Explanation

flags	Specifies the relative location of the pop-up menu. It can be one of the following values:

 	TPM_CENTERALIGN
TPM_LEFTALIGN
TPM_RIGHTALIGN
TPM_LEFTBUTTON
TPM_RIGHTBUTTON

x and y	Specify the screen location of the pop-up menu. In the second form of TrackPopupMenu, point does the same thing, combining x and y into a single TPoint object. The menu is then created relative to this point, depending on the value of flags.

rsvd	A reserved value that must be set to 0.

wnd	The handle to the window that receives messages about the menu.

rect	Defines the area that the user can click without dismissing the menu.

The following example shows a window class that displays a pop-up menu in response to a right mouse button click:

class TPopupMenuFrame : public TFrameWindow

{

  public:

    TPopupMenuFrame(TWindow* parent, const char *name);

  protected:

    TPopupMenu PopupMenu;

    void EvRButtonDown(uint modKeys, TPoint& point);

  DECLARE_RESPONSE_TABLE(TPopupMenuFrame);

};

DEFINE_RESPONSE_TABLE1(TSysMenuFrame, TFrameWindow)

  EV_WM_RBUTTONDOWN,

END_RESPONSE_TABLE;

TPopupMenuFrame::TPopupMenuFrame(TWindow* parent, const char *name)

  : TFrameWindow(parent, name)

{

  PopupMenu.AppendMenu(MF_STRING, CM_FILENEW, "Create new file");

  PopupMenu.AppendMenu(MF_STRING, CM_FILEOPEN, "Open file");

  PopupMenu.AppendMenu(MF_STRING, CM_FILESAVE, "Save file");

  PopupMenu.AppendMenu(MF_STRING, CM_FILESAVEAS,
    "Save file under new name");

  PopupMenu.AppendMenu(MF_STRING, CM_PENSIZE, "Change pen size");

  PopupMenu.AppendMenu(MF_STRING, CM_PENCOLOR, "Change pen color");

  PopupMenu.AppendMenu(MF_STRING, CM_ABOUT, "&About...");

  PopupMenu.AppendMenu(MF_STRING, CM_EXIT, "Exit Program");

}

void

TPopupMenuFrame::EvRButtonDown(uint /* modKeys */, TPoint& point)

{

  PopupMenu.TrackPopupMenu(TPM_LEFTBUTTON, point, 0, HWindow);

}


See Also

Menu Objects Overview (ObjectWindows)


Using Menu Objects with Frame Windows (ObjectWindows)

ObjectWindows frame window objects (TFrameWindow and TFrameWindow-derived classes) provide a number of functions that you can use to assign, change, and modify menus. There are two ways to manipulate frame window menus:

 Directly assign or change the frame window's main menu. This is typically how you work with menus when you have a single menu that does not use menu merging.

Assign and merge the frame window's menu descriptor with that of client and child windows. Menu descriptors are objects that divide the menu bar into functional groups and permit easy merging and removal of popup menus.

These two methods of using menu objects are described in

Adding Menu Resources To Frame Windows

Using Menu Descriptors


Adding Menu Resources To Frame Windows (ObjectWindows)

See Also

Instead of assigning a menu resource directly to the Attr.Menu member of a frame window (for example, Attr.Menu = MENU_1;), you must use the AssignMenu function, as in the following example:

AssignMenu(MENU_1);

AssignMenu is defined in the TFrameWindow class and is available in any class derived from TFrameWindow, such as TMDIFrame, TMDIChild, TDecoratedFrame, and TFloatingFrame. It takes a TResId for its only parameter and returns true if the assignment operation was successful. AssignMenu is declared virtual, so you can override it in your own TFrameWindow-derived classes.

You can change the menu after the frame window has been created. To change the frame window's menu, call the window object's SetMenu function.

SetMenu(MENU_2);


See Also

Using Menu Descriptors

Menu Objects Overview


Using Menu Descriptors (ObjectWindows
Using Menu Descriptors (ObjectWindows)

See Also

Managing menus (adding menus for child windows, merging menus, and so on) can be a tedious and confusing chore. ObjectWindows simplifies menu management with objects known as menu descriptors, which divide the menu bar into the following six groups, corresponding to conventional ways of arranging functions on a menu bar:

 	File

 	Edit

 	Container

 	Object

 	Window

 	Help

Organizing menus into functional groups makes it easy to insert a new menu into an existing menu bar. For example, consider an MDI application, such as Step 11 of the tutorial in the Learning ObjectWindows manual. The frame and client windows provide menus that let the user perform general application functions such as opening files, managing windows, and so on. The child windows handle the menu commands for functions specific to a particular drawing, such as setting the line width and color.

In the tutorial, the menu stays the same, but menu items handled by the child windows are grayed out when no child window is available to handle the command. An additional way to handle this would be to have the menu bar populated only with the menus handled by the frame and client windows. Then, when a child window is opened, the menus handled by the child window would be merged into the existing menu bar. The following figures show how an application that uses both these techniques looks to the user:

The first figure shows the application with no child windows open.

The second figure shows the application after a child window has been opened.

Adding menu descriptors to an application is a simple process:

1.	Set the menu descriptor for the frame window's menu bar by calling the frame window's SetMenuDescr function.

2.	When creating a new child window, set the child's menu descriptor by calling the child's SetMenuDescr function. After the child window is created, ObjectWindows automatically merges the menu from the child with the frame window's menu bar while the child is active. Note that different MDI child windows in the same application can have different menu descriptors. This is useful when the child windows contain different kinds of documents.

To learn more about creating menu descriptors and using the menu descriptor handling functions, see the following topics:

Creating Menu Descriptors

Constructing Menu Descriptor Objects

Merging Menus With Menu Descriptors


See Also

Menu Objects Overview

Adding Menu Resources To Frame Windows

Creating Menu Descriptors

Constructing Menu Descriptor Objects

Merging Menus With Menu Descriptors


Menu descriptor application without child windows open

Notice that there are only four active popup menus on the menu bar. Edit is grayed out because no child window is active.


Menu descriptor application with child windows open

Notice that the Edit popup is now active and that there is an extra popup menu labeled Tools. The Tools menu is merged into the main menu bar only when there is a child window where the tools can be used.


Creating Menu Descriptors
Creating Menu Descriptors (ObjectWindows)

See Also

The TMenuDescr class implements menu descriptor functionality. Menu descriptors take a menu resource and place the separate pop-up menus in the resource into six functional groups. The naming of the groups is arbitrary; you are not restricted to putting only menus of a certain functional type into a particular group. However, the naming convention does reflect standard conventions of menu item placement. These names are contained in the TGroup enum:

 	FileGroup

 	EditGroup

 	ContainerGroup

 	ObjectGroup

 	WindowGroup

 	HelpGroup

These groups are arranged consecutively on the menu bar from left to right. When another menu descriptor is merged with the existing menu bar, the new pop-up menus are merged according to their groups. For example, consider the two figures from Using Menu Descriptors.

In the first figure, the original pop-up menus are placed in the following menu groups:

 	The File menu is placed in the FileGroup group.

 	The Edit menu is placed in the EditGroup group.

 	The Window menu is placed in the WindowGroup group.

 	The Help menu is placed in the HelpGroup group.

When the child window is created, its pop-up menu, called Tools, is placed in the ContainerGroup group. Then, when the menus are merged in the second figure, the child window's menu is automatically placed between the Edit menu and the Window menu.


See Also

Using Menu Descriptors (introduction to menu descriptors)

Constructing Menu Descriptor Objects

Merging Menus With Menu Descriptors


Constructing Menu Descriptor Objects
Constructing Menu Descriptor Objects (ObjectWindows)

See Also

You can specify the grouping of your menu resources in the TMenuDescr constructor. There are a number of different constructors for TMenuDescr, all of which are  described in the following table.

Constructor	Description

TMenuDescr(TResId id,	Creates a menu descriptor from the menu

TModule* module = ::Module)	resource identified by id. The grouping of the pop-up menus are determined by the occurrence of separators at the menu level (that is, separators inside of a pop-up menu are disregarded for grouping purposes) in the menu resource. Menu separators are discussed in more detail in Creating Menu Groups In Menu Resources.

.

TMenuDescr(TResId id,	Creates a menu descriptor from the menu resource

int fg, int eg, int cg,	identified by id or hMenu. The separate pop-ups in the

int og, int wg, int hg,	resource are then placed in groups according to the

TModule* module = ::Module)	values of fg, eg, cg, og, wg, and hg, which correspond to the groups defined in the TGroup enum. The total of

TMenuDescr(HMENU hMenu,	all the values of these group parameters is equivalent

 	int fg, int eg, int cg,	to the number of pop-ups in the menu resource.

int og, int wg, int hg,

TModule* module = ::Module)

TMenuDescr()	Creates a default menu constructor without menu resources or group counts.

TMenuDescr(const TMenuDescr& original)	Creates a copy of the menu descriptor object original.


See Also

Using Menu Descriptors (introduction to menu descriptors)

Creating Menu Descriptors

Creating Menu Groups In Menu Resources

Merging Menus With Menu Descriptors


Creating Menu Groups in Menu Resources

See Also

The TMenuDescr class provides two ways to set up the groups that your various pop-up menus belong in:

Explicitly numbering the menu resources in the TMenuDescr constructor

Placing separators at the pop-up menu level in the menu resource

Earlier versions of ObjectWindows provided only the first method. The second method is new in ObjectWindows 2.5 . This method is more flexible, eliminating the need to modify the TMenuDescr constructor whenever you add or remove a pop-up menu in your menu resource.

To set up groups in your menu resource, put separators at the pop-up menu level, outside the pop-up definitions. These separators have meaning only to the TMenuDescr constructor and do not cause any changes in the appearance of your menu bar. Separators inside pop-up menus are treated normally: They appear in the pop-up menu as separator bars between menu choices.

The following example shows how a menu resource might be divided up into groups using separators in the menu resource. The menu resource is divided up into the requisite six groups, with four of the groups containing actual pop-up menus: the File menu, the Edit menu, the Window menu, and the Help menu. The other two groups are empty.

IDM_COMMANDS MENU

{

  POPUP "File"

  {

    MENUITEM "&New\aCtrl+N", CM_FILENEW

    MENUITEM "&Open\aCtrl+O", CM_FILEOPEN

    MENUITEM "&Save\aCtrl+S", CM_FILESAVE

    MENUITEM "Save &as...", CM_FILESAVEAS

    MENUITEM SEPARATOR

    MENUITEM "&Print\aCtrl+P", CM_FILEPRINT

  }

  MENUITEM SEPARATOR

  POPUP "&Edit"

  {

    MENUITEM "&Undo\aCtrl+Z", CM_EDITUNDO

    MENUITEM Separator

    MENUITEM "&Cut\aCtrl+X", CM_EDITCUT

    MENUITEM "C&opy\aCtrl+C", CM_EDITCOPY

    MENUITEM "&Paste\aCtrl+V", CM_EDITPASTE

    MENUITEM "&Delete\aDel", CM_EDITDELETE

  }

  MENUITEM SEPARATOR

  MENUITEM SEPARATOR

  MENUITEM SEPARATOR

  POPUP "&Window"

  {

    MENUITEM "&Cascade", CM_CASCADECHILDREN

    MENUITEM "&Tile", CM_TILECHILDREN

    MENUITEM "Arrange &Icons", CM_ARRANGEICONS

    MENUITEM "C&lose All", CM_CLOSECHILDREN

    MENUITEM "Add &View", CM_VIEWCREATE

  }

  MENUITEM SEPARATOR

  POPUP "&Help"

  {

    MENUITEM "&About", CM_ABOUT

  }

}


See Also

Menu Objects Overview

Using Menu Descriptors (introduction to menu descriptors)

Creating Menu Descriptors

Merging Menus With Menu Descriptors


Merging Menus with Menu Descriptors
Merging Menus with Menu Descriptors (ObjectWindows)

See Also

To use menu descriptors to merge menus, set your frame window's menu descriptor sometime before the creation of the window, usually during the InitMainWindow function. Then whenever you want to merge a child window's menu or menus with that of its parent, you set the child window's menu descriptor before creating the child. When child is created, its menu descriptor is automatically merged with the parent.

You set a window's menu descriptor using the SetMenuDescr function. SetMenuDescr returns a void and takes a const TMenuDescr reference as its only parameter. The following example shows how you might create and set the menu descriptors for the example discussed in  Using Menu Descriptors:

class TMenuDescrApp : public TApplication

{

  public:

    TMenuDescrApp(const char* name) : TApplication(name) {}

    void InitMainWindow()

    {

      SetMainWindow(Frame = new TMDIFrame(Name, COMMANDS,

                    *new TMenuDescrMDIClient));

      Frame>SetMenuDescr(TMenuDescr(COMMANDS));

    }

  protected:

    TMDIFrame* Frame;

};

void

TMenuDescrMDIClient::CmAddMenu1()

{

  TMDIChild *child = new TMDIChild(*this, "Child Window 1",

                                   new TMenuDescrWindow, true);

  child>SetMenuDescr(TMenuDescr(IDM_MENU1));

  child>Create();

}


See Also

Using Menu Descriptors (introduction to menu descriptors)

Constructing Menu Descriptor Objects

Creating Menu Descriptors

Creating Menu Groups In Menu Resources


Dialog Box Objects Overview (ObjectWindows)

Dialog box objects are interface objects that encapsulate the behavior of dialog boxes. The TDialog class supports initializing, creating, and executing of all types of dialog boxes. As with window objects derived from TWindow, you can derive specialized dialog box objects from TDialog for each dialog box your application uses.

ObjectWindows also supplies classes that encapsulate Windows' common dialog boxes. Windows provides common dialog boxes as a way to let users choose file names, fonts, colors, and so on.

To use dialog box objects, you will be performing the following tasks:

Using dialog box objects

Using a dialog box as your main window

Manipulating controls in dialog boxes

Associating interface objects with controls

Using common dialog boxes


Using Dialog Box Objects (ObjectWindows)

Using dialog box objects is a lot like using window objects. For simple dialog boxes that appear for only a short period of time, you can control the dialog box in one member function of the parent window. You can construct, execute, and destroy the dialog box object in the member function.

Using a dialog box object requires the following steps:

Constructing the object

Executing the dialog box

Closing and destroying the dialog box

You also might want to know how to

Use a Dialog Box As Your Main Window


Constructing a Dialog Box Object (ObjectWindows)

See Also

Dialog boxes are designed and created using dialog box resources. You can use Borland's Resource Workshop or any other resource editor to create dialog box resources and bind them to your application. A dialog box resource describes the appearance and location of controls, such as buttons, list boxes, group boxes, and so on, but is not responsible for the behavior of the dialog box. That is the responsibility of the application.

Each dialog box resource has an identifier that enables a dialog box object to specify which dialog box resource it uses. The identifier can be either a string or an integer. You pass this identifier to the dialog box constructor to specify which resource the object should use.

Calling the Constructor

To construct a dialog box object, create it using a pointer to a parent window object and a resource identifier (the resource identifier can be either string or integer based) as the parameters to the constructor:

TDialog dialog1(this, "DIALOG_1");

TDialog dialog2(this, IDD_MY_DIALOG);

The parent window is almost always this, since you normally construct dialog box objects in a member function of a window object. If you do not construct a dialog box object in a window object, use the application's main window as its parent as shown in the following code sample, because that is the only window object always present in an ObjectWindows application:

TDialog mySpecialDialog(GetApplication()->GetMainWindow(), IDD_DLG);

The exception to this parent window behavior is when you specify a dialog box object as a client window in a TFrameWindow or TFrameWindow-based constructor. The constructor passes the dialog box object to the TFrameWindow::Init function, which automatically sets the parent of the dialog box. (See Using a Dialog Box as Your Main Window for an example.)


See Also

Closing the Dialog Box

Using a Dialog Box as Your Main Window

Using Dialog Box Objects


Executing a Dialog Box (ObjectWindows)

See Also

Executing a dialog box is analogous to creating and displaying a window. However, because dialog boxes are usually displayed for a shorter period of time, some of the steps can be abbreviated. This depends on whether you are using

modal dialog boxes

modeless dialog box

A way to save time is to use autocreation with dialog boxes to do the work of explicitly creating your child dialog objects.

Once created and displayed, you will also need to know how to

manage dialog boxes,

handle errors in executing dialog boxes,

close dialog boxes.


See Also

Closing the Dialog Box

Constructing a Dialog Box Object


Modal Dialog Boxes (ObjectWindows)

See Also

Most dialog boxes are modal. While a modal dialog box is displayed, the user cannot select or use its parent window, but rather must close the dialog box before proceeding. In effect, a modal dialog box freezes the operation of the rest of the application.

Use TDialog::Execute to execute a dialog box modally. When the user closes the dialog box, Execute returns an integer value indicating how the user closed the dialog box. The return value is the identifier of the control the user pressed, such as IDOK for the OK button or IDCANCEL for a Cancel button. If the dialog box object was dynamically allocated, be sure to delete the object.

Example

The following example assumes you have a dialog resource IDD_MYDIALOG, and that the dialog box has two buttons, an OK button that sends the identifier value IDOK and a Cancel button that sends some other value:

if(TDialog(this, IDD_MYDIALOG).Execute() == IDOK)

  // User pressed the OK button.

else

  // User pressed Cancel.

Only the object is deleted when it goes out of scope, not the dialog box resource. You can create and delete any number of dialog boxes with a single dialog box resource.


See Also

Managing Dialog Boxes

Modeless Dialog Boxes

Handling Errors When Executing Dialog Boxes

Using Autocreation with Dialog Boxes


Modeless Dialog Boxes (ObjectWindows)

See Also

Unlike modal dialog boxes, a modeless dialog box allows you to continue using other windows in your application while it is open. You can use a modeless dialog box to let the user continue to perform actions, find information, and so on, while still using the dialog box.

Use TDialog::Create to execute a modeless dialog box. When using Create to execute a dialog box, you must explicitly make the dialog box visible by either specifying the WS_VISIBLE flag for the resource style or using the ShowWindow function to force the dialog box to display itself.

Example

For example, suppose your resource script file looks something like this:

DIALOG_1 DIALOG 18, 18, 142, 44

STYLE DS_MODALFRAME | WS_POPUP | WS_CAPTION | WS_SYSMENU

CAPTION "Dialog 1"

{

  PUSHBUTTON "Button", IDOK, 58, 23, 25, 16

}

Now, suppose you try to create this dialog box modelessly using the following code:

  .

  .

  .

TDialog dialog1(this, "DIALOG_1");

dialog1.Create();

  .

  .

  .

This dialog box would not appear on your screen. To make it appear, you would have to do one of two things:

Change the style of the dialog box so that the WS_VISIBLE flag is set:

STYLE DS_MODALFRAME | WS_POPUP | WS_CAPTION | WS_SYSMENU | WS_VISIBLE

Add the ShowWindow function after the call to Create:

  .

  .

  .

TDialog dialog1(this, "DIALOG_1");

dialog1.Create();

dialog1.ShowWindow(SW_SHOW);

  .

  .

  .

The TDialog::CmOk and TDialog::CmCancel functions close the dialog box and delete the object. These functions handle the IDOK and IDCANCEL messages, usually sent by the OK and Cancel buttons, in the TDialog response table. The CmOk function calls CloseWindow to close down the modeless dialog box. The CmCancel function calls Destroy with the IDCANCEL parameter. Both these functions close the dialog box. If you override either CmOk or CmCancel, you need to either call the base class CmOk or CmCancel function in your overriding function or perform the closing and cleanup operations yourself.

Alternately, you can create your dialog box object in the constructor for the parent of the dialog box. This way, you create the dialog box object just once. Furthermore, any changes made to the dialog box state, such as its location, active focus, and so on, are kept the next time you open the dialog box.

Like any other child window, the dialog box object is automatically deleted when its parent is destroyed. This way, if you close down the dialog box's parent, the dialog box object is automatically destroyed; you do not need to explicitly delete the object.

More specifically, ObjectWindows' default behavior when the user closes a modeless dialog box is to close the dialog window, but not to delete its pointer and not to call its class's destructor. If the dialog object has a parent window, the dialog object's pointer is deleted (and its destructor is called) when the parent window closes. If there is no parent window, the pointer is not automatically deleted.

You can override this default behavior by setting the wfDeleteOnClose flag in the dialog object's class constructor (call SetFlag(wfDeleteOnClose)). Setting wfDeleteOnClose causes ObjectWindows to automatically delete the pointer and call the class destructor of a modeless dialog object when the dialog window receives a WM_CLOSE message (when the user closes it). Setting this flag has no effect on modal dialog boxes.

Example

In the following code fragment, a parent window constructor just constructs a dialog box object, and another function actually creates and displays the modal dialog box:

class TParentWindow : public TFrameWindow

{

  public:

    TParentWindow(TWindow* parent, const char* title);

    void CmDOIT();

  protected:

    TDialog *dialog;

};

  .

  .

  .

void TParentWindow::CmDOIT()

{

  dialog = new TDialog(this, IDD_EMPLOYEE_INFO);

  dialog->Create();

}


See Also

Handling Errors When Executing Dialog Boxes

Managing Dialog Boxes

Modal Dialog Boxes

Using Autocreation with Dialog Boxes


Using Autocreation with Dialog Boxes (ObjectWindows)

See Also

You can use autocreation to let ObjectWindows do the work of explicitly creating your child dialog objects for you. By creating the objects in the constructor of a TWindow-derived class and specifying the this pointer as the parent, the TWindow-derived class builds a list of child windows. You can produce the same behavior if you make the dialog box object a data member of the parent class. Then, when the TWindow-derived class is created, it attempts to create all the children in its list that have the wfAutoCreate flag turned on, resulting in the children appearing on the screen at the same time as the parent window.

Turn on the wfAutoCreate flag using the function EnableAutoCreate. Turn off the wfAutoCreate flag using the function DisableAutoCreate.

TWindow uses Create for autocreating its children. Thus any dialog boxes created with autocreation are modeless dialog boxes.

Just as with regular modeless dialog boxes, if you are using autocreation to turn your dialog boxes on, you must make your dialog box visible; however, with autocreation you must turn the WS_VISIBLE flag on in the resource file. You cannot use the ShowWindow function to enable autocreation.

Example

The following code shows how to enable autocreation for a dialog box:

class TMyFrame : public TFrameWindow

{

  public:

    TDialog *dialog;

    TMyFrame(TWindow *, const char far *);

};

TMyFrame::TMyFrame(TWindow *parent, const char far *title)

{

  Init(parent, true);

  dialog = new TDialog(this, "MYDIALOG");

  // For the next line to work properly, the WS_VISIBLE attribute

  // must be specified for the MYDIALOG resource.

  dialog->EnableAutoCreate();

}

When you execute this application, the dialog box is automatically created for you.


See Also

Handling Errors When Executing Dialog Boxes

Managing Dialog Boxes

Modal Dialog Boxes

Modeless Dialog Boxes

Constructing Window Objects


Managing Dialog Boxes (ObjectWindows)

See Also

Dialog boxes, unlike other child windows, such as windows and controls, are often displayed and destroyed many times during the life of their parent windows, but are rarely displayed or destroyed at the same time as their parents. Usually, an application displays a dialog box in response to a menu selection, mouse click, error condition, or other event.

Therefore, you must be sure to not repeatedly construct new dialog box objects without deleting previous ones. Remember that when you construct a dialog box object in its parent window object's constructor or include the dialog box as a data member of the parent window object, the dialog box object is inserted into the child-window list of the parent and deleted when the parent is destroyed.

You can retrieve data from a dialog box at any time, as long as the dialog box object still exists. You will do this most often in the dialog box object's CmOK member function, which is called when the user presses the dialog box's OK button.


See Also

Handling Errors When Executing Dialog Boxes

Modal Dialog Boxes

Modeless Dialog Boxes

Using Autocreation with Dialog Boxes


Handling Errors While Executing Dialog Boxes (ObjectWindows)
Handling Errors When Executing Dialog Boxes (ObjectWindows)

See Also

Like window objects, a dialog box object's Create and Execute member functions can throw the C++ exception TXWindow. This exception is usually thrown when the dialog box cannot be created, typically because the specified resource does not exist or because of insufficient memory.

You can rely on the global exception handler that ObjectWindows installs when your application starts to catch TXWindow, or you can install your own exception handler. To install your own exception handler, place a try/catch block around the code you want to protect.

Example

For example, if you want to know if your function DoStuff produces an error, the code would look something like this:

try {

  DoStuff();

}

catch(TWindow::TXWindow& e) {

  // You can do whatever exception handling you like here.

  MessageBox(0, e.why().c_str(),

             "Error", MB_OK);

}


See Also

Managing Dialog Boxes

Modal Dialog Boxes

Modeless Dialog Boxes

Using Autocreation with Dialog Boxes


Closing the Dialog Box (ObjectWindows)

See Also

Every dialog box must have a way for the user to close it. For dialog boxes, this is usually an OK or Cancel button, or both. TDialog has the event response functions CmOk and CmCancel to respond to those buttons.

CmOk calls CloseWindow, which calls CanClose to see if it is OK to close the dialog box. If CanClose returns true, CloseWindow transfers the dialog's data and closes the dialog box by calling TWindow::CloseWindow.

CmCancel calls EvClose, which in turn calls Destroy,  which closes the dialog box. No checking of CanClose is performed, and no transfer is done.

To verify the input in a dialog box, you can override the dialog box object's CanClose member function. If you override CanClose, be sure to call the parent TWindow::CanClose function, which handles calling CanClose for child windows.


See Also

Constructing a Dialog Box Object

Using Dialog Box Objects


Using a Dialog Box As Your Main Window (ObjectWindows)

See Also

To use a dialog box as your main window, it is best to make the main window a frame window that has your dialog box as a client window. To do this, derive an application class from TApplication. Aside from a constructor, the only function necessary for this purpose is InitMainWindow. In the InitMainWindow function, construct a frame window object, specifying a dialog box as the client window. In the five-parameter TFrameWindow constructor, pass a pointer to the client window as the third parameter. Your code should look something like this:

#include <owl\applicat.h>

#include <owl\framewin.h>

#include <owl\dialog.h>

class TMyApp : public TApplication

{

  public:

    TMyApp(char *title) : TApplication(title) {}

    void InitMainWindow();

};

void TMyApp::InitMainWindow()

{

  SetMainWindow(new TFrameWindow(0, "My App",

                                 new TDialog(0, "MYDIALOG"), true));

}

int OwlMain(int argc, char* argv[])

{

  return TMyApp("My App").Run();

}

The TFrameWindow constructor turns autocreation on for the dialog box object that you pass as a client, regardless of the state you pass it in.

You also must make sure the dialog box resource has certain attributes:

Destroying your dialog object does not destroy the frame. You must destroy the frame explicitly.

You can no longer dynamically add resources directly to the dialog, because it is not the main window. You must add the resources to the frame window. For example, suppose you added an icon to your dialog using the SetIcon function. You now must use the SetIcon function for your frame window.

You cannot specify the caption for your dialog in the resource itself anymore. Instead, you must set the caption through the frame window.

You must set the style of the dialog box as follows:

Visible (WS_VISIBLE)

Child window (WS_CHILD)

No Minimize and Maximize buttons, drag bars, system menus, or any of the other standard frame window attributes


See Also

Associating Interface Objects with Controls

Manipulating Controls in Dialog Boxes

Using Dialog Box Objects

Using Dialog Boxes


Manipulating Controls in Dialog Boxes (ObjectWindows)

See Also

Almost all dialog boxes have, as child windows, controls such as edit controls, list boxes, buttons, and so on. Those controls are created from the dialog box resource.

Communicating with Controls

There is a two-way communication between a dialog box object and its controls. In one direction, the dialog box needs to manipulate its controls; for example, to fill a list box. In the other direction, it needs to process and respond to the messages the controls generate; for example, when the user selects an item from a list box.

Windows defines a set of control messages that are sent from the application back to Windows. For example, list-box messages include LB_GETTEXT, LB_GETCURSEL, and LB_ADDSTRING.

It is rarely necessary to use control messages to communicate with controls: ObjectWindows control classes provide member functions to perform the same actions. The purpose of discussing these communication mechanisms is simply to enhance your understanding of the process.

Control messages specify the specific control and pass along information in wParam and lParam arguments. Each control in a dialog resource has an identifier that you use to specify the control that receives the message. To send a control message, you can call SendDlgItemMessage. For example, the following member function adds the specified string to the list box using the LB_ADDSTRING message:

void TTestDialog::FillListBox(const char far* string)

{

  SendDlgItemMessage(ID_LISTBOX, LB_ADDSTRING, 0, (LPARAM)string);

}

Note:	TListBox::AddString does basically the same thing as this function and is easier to understand; however. you can use SendDlgItemMessage to force actions.


See Also

Associating Interface Objects with Controls

Control Objects Overview

Interface Objects Overview

Using a Dialog Box As Your Main Window

Using Dialog Box Objects

Using Dialog Boxes


Associating Interface Objects with Controls (ObjectWindows)

See Also

Because a dialog box is created from its resource, you do not use C++ code to specify what it looks like or the controls in it. Although this use of the resource lets you create the dialog box visually, it makes it harder to manipulate the controls from your application. ObjectWindows overcomes this limitation by letting you associate (connect) controls in a dialog box with interface objects, allowing you to

Provide specialized responses to messages. For example, you might want an edit control that allows only digits to be entered, or you might want a button that changes styles when it is pressed.

Use member functions and data members to manipulate the control, which is easier and more object-oriented than using control messages.

Control Objects

To associate a control object with a control element, you can define a pointer to a control object as a data member and construct a control object in the dialog box object's constructor. Control classes such as TButton have a constructor that takes a pointer to the parent window object and the control's resource identifier. In the following example, TTestDialog's constructor creates a TButton object from the resource ID_BUTTON:

TTestDialog::TTestDialog(TWindow* parent, const char* resID)

  : TDialog(parent, resID),

    TWindow(parent)

{

  new TButton(this, ID_BUTTON);

}

You can also define your own control class, derived from an existing control class (if you want to provide specialized behavior). In the following example, TBeepButton is a specialized TButton that overrides the default response to the BN_CLICKED notification code. A TBeepButton object is associated with the ID_BUTTON button resource.

class TBeepButton : public TButton

{

  public:

    TBeepButton(TWindow* parent, int resId):TButton(parent, resId) {}

    void BNClicked();  // BN_CLICKED

    DECLARE_RESPONSE_TABLE(TBeepButton);

};

DEFINE_RESPONSE_TABLE1(TBeepButton, TButton)

  EV_NOTIFY_AT_CHILD(BN_CLICKED, BNClicked),

END_RESPONSE_TABLE;

void TBeepButton::BNClicked()

{

  MessageBeep(-1);

}

.

.

.

TBeepDialog::TBeepDialog(TWindow* parent, const char* name)

  : TDialog(parent, name), TWindow(parent)

{

  button = new TBeepButton(this, ID_BUTTON);

}

Unlike setting up a window object, which requires two steps (construction and creation), associating an interface object with an interface element requires only the construction step. This is because the interface element already exists: it is loaded from the dialog box resource. You just have to tell the constructor which control from the resource to use, using its resource identifier.


See Also

Manipulating Controls in Dialog Boxes

Using a Dialog Box As Your Main Window

Using Dialog Box Objects

Using Dialog Boxes


Setting Up Controls (ObjectWindows)

See Also

You cannot manipulate controls by adding strings to a list box or setting the font of an edit control until the dialog box object's SetupWindow member function executes.  Until TDialog::SetupWindow has called TWindow::SetupWindow, the dialog box's controls have not been associated with the corresponding objects. Once they are associated, the objects' HWindow data members are valid for the controls.

In this example, the AddString function is not called until the base class SetupWindow function is called:

class TDerivedDialog : public TDialog

{

  public:

    TDerivedDialog(TWindow* parent, TResId resId)

      : TDialog(parent, resId), TWindow(parent)

    {

      listbox = new TListBox(this, IDD_LISTBOX);

    }

  protected:

    TListBox* listbox;

};

void TDerivedDialog::SetupWindow()

{

  TDialog::SetupWindow();

  listbox->AddString("First entry");

}


See Also

Associating Interface Objects with Controls

Manipulating Controls in Dialog Boxes


Using Dialog Boxes (ObjectWindows)

See Also

A Windows application often needs to prompt the user for file names, colors, or fonts. ObjectWindows provides classes that make it easy to use dialog boxes, including input dialog boxes and common dialog boxes.

The following table lists the different types of dialog boxes and the ObjectWindows class that  encapsulates each one.

Type	ObjectWindows class

Color	TChooseColorDialog

Font	TChooseFontDialog

File open	TFileOpenDialog

File save	TFileSaveDialog

Find string	TFindDialog

Input from user	TInputDialog

Printer abort dialog	TPrinterAbortDlg

Printer control	TPrintDialog

Replace string	TReplaceDialog


See Also

Associating Interface Objects with Controls

Manipulating Controls in Dialog Boxes

Using a Dialog Box As Your Main Window

Using Dialog Box Objects

Using Dialog Boxes


Using Input Dialog Boxes (ObjectWindows)

See Also

Input dialog boxes are simple dialog boxes that prompt the user for a single line of text input. You can run input dialog boxes as either modal or modeless dialog boxes, but you will usually run them modally. Input dialog box objects have a dialog box resource associated with them, provided in the resource script file owl\inputdia.rc. Your application's .RC file must include owl\inputdia.rc.

When you construct an input dialog box object, you specify a pointer to the parent window object, a caption, a prompt, and the text buffer and its size. The contents of the text buffer is the default input text. When the user chooses OK or presses Enter, the line of text entered is automatically transferred into the character array.

Example

Here is an example:

char patientName[33] = "";

TInputDialog(this, "Patient name",

             "Enter the patient's name:",

             patientName, sizeof(patientName)).Execute();

In this example, patientName is a text buffer that gets filled with the user's input when the user chooses OK. It is initialized to an empty string for the default text.


See Also

Using Color Common Dialog Boxes

Using Common Dialog Boxes

Using File Open Common Dialog Boxes

Using File Save Common Dialog Boxes

Using Find and Replace Common Dialog Boxes

Using Font Common Dialog Boxes

Using Printer Common Dialog Boxes


Using Common Dialog Boxes (ObjectWindows)

The common dialog boxes encapsulate the functionality of the Windows common dialog boxes. These dialog boxes let the user choose colors, fonts, file names, find and replace strings, print options, and more. You construct, execute, and destroy them all in a similar manner. To take advantage of common dialog boxes, you will be performing the following tasks:

Constructing Common Dialog Boxes

Executing Common Dialog Boxes

Using Color Common Dialog Boxes

Using Font Common Dialog Boxes

Using File Open Common Dialog Boxes

Using File Save Common Dialog Boxes

Using Find And Replace Common Dialog Boxes

Constructing And Creating Find And Replace Common Dialog Boxes

Processing Find And Replace Messages

Handling A Find Next Command

Using Printer Common Dialog Boxes


Constructing Common Dialog Boxes (ObjectWindows)

See Also

Each common dialog box class has a nested class called TData that contains some common housekeeping members and data specific to each type of common dialog box. For example, TChooseColorDialog::TData has members for the color being chosen and an array for a set of custom colors. The following table lists the two members common to all TData nested classes.

Name	Type	Description

Flags	uint32	A set of common dialog box-specific flags that control the appearance and behavior of the dialog box. For example, CC_SHOWHELP is a flag that tells the color selection common dialog box to display a Help button the user can press to get context-sensitive Help.

Error	uint32	An error code used if an error occurred while processing a common dialog box; zero if no error occurred. Because Execute returns IDCANCEL both when the user chose Cancel and when an error occurred, you must check Error to determine whether an error actually occurred.

Each common dialog box class has a constructor that takes a pointer to a parent window object, a reference to that class's TData nested class, and optional parameters for a custom dialog box template, title string, and module pointer.

Here is a sample fragment that constructs a common color selection dialog box:

TChooseColorDialog::TData colors;

static TColor custColors[16] =

{

  0x010101L, 0x101010L, 0x202020L, 0x303030L,

  0x404040L, 0x505050L, 0x606060L, 0x707070L,

  0x808080L, 0x909090L, 0xA0A0A0L, 0xB0B0B0L,

  0xC0C0C0L, 0xD0D0D0L, 0xE0E0E0L, 0xF0F0F0L

};

colors.CustColors = custColors;

colors.Flags = CC_RGBINIT;

colors.Color = TColor::Black;

if (TChooseColorDialog(this, colors).Execute() == IDOK)

  SetColor(colors.Color);

After the user has chosen a new color in the dialog box and pressed OK, that color is placed in the Color member of the TData object.


See Also

Constructing Common Dialog Boxes

Executing Common Dialog Boxes


Executing Common Dialog Boxes (ObjectWindows)

See Also

After you have constructed the common dialog box object, you either execute it (for a modal dialog box) or create it (for a modeless dialog box). The following table lists whether each type of common dialog box must be modal or modeless.

Type	Modal or modeless	Run by calling

Color	Modal	Execute

Font	Modal	Execute

File open	Modal	Execute

File save	Modal	Execute

Find	Modeless	Create

Find/replace	Modeless	Create

Printer	Modal	Execute

You must check Execute's return value to see whether the user chose OK or Cancel, or to determine if an error occurred. For example,

TChooseColorDialog::TData colors;

TChooseColorDialog colorDlg(this, colors);

if (colorDlg.Execute() == IDOK)

  // OK: data.Color == the color the user chose

  // Some code here

else if (data.Error)

  // error occurred!

  // Some code here

  MessageBox("Error in color dialog box!", GetApplication()->Name,

             MB_OK | MB_ICONSTOP);


See Also

Constructing Common Dialog Boxes

Executing Common Dialog Boxes


Using Color Common Dialog Boxes (ObjectWindows)

See Also

The color common dialog box lets you choose and create colors for use in your application. For example, a paint application might use the color common dialog box to choose the color of a paint bucket.

TChooseColorDialog::TData has several members you must initialize before constructing the dialog box object:

TData member	Type	Description

Color	TColor	The selected color. When you execute the dialog box, Color specifies the default color. When the user closes the dialog box, Color specifies the color the user chose.

CustColors	TColor*	A pointer to an array of sixteen custom colors. On input, it specifies the default custom colors. On output, it specifies the custom colors the user chose.

In the following example, a color common dialog box is used to set the window object's Color member, which is used elsewhere to paint the window. Note the use of the TWindow::Invalidate member function to force the window to be repainted in the new color.

void TCommDlgWnd::CmColor()

{

  // use static to keep custom colors around between

  // executions of the color common dialog box

  static TColor custColors[16];

  TChooseColorDialog::TData choose;

  choose.Flags = CC_RGBINIT;

  choose.Color = Color;

  choose.CustColors = custColors;

  if(TChooseColorDialog(this, choose).Execute() == IDOK)

    Color = choose.Color;

  Invalidate();

}


See Also

TChooseColorDialog

TChooseColorDialog::TData::Flags

Using Common Dialog Boxes

Using File Open Common Dialog Boxes

Using File Save Common Dialog Boxes

Using Find and Replace Common Dialog Boxes

Using Font Common Dialog Boxes

Using Input Dialog Boxes

Using Printer Common Dialog Boxes


Using Font Common Dialog Boxes (ObjectWindows)

See Also

The font common dialog box lets you choose a font to use in your application, including the typeface, size, style, and so on. For example, a word processor might use the font common dialog box to choose the font for a paragraph.

TChooseFontDialog::TData has several members you must initialize before constructing the dialog box object:

TData member	Type	Description

DC	HDC	A handle to the device context of the printer whose fonts you want to select, if you specify CF_PRINTERFONTS in Flags. Otherwise ignored.

LogFont	LOGFONT	A handle to a LOGFONT that specifies the font's appearance. When you execute the dialog box and specify the flag CF_INITTOLOGFONTSTRUCT, the dialog box appears with the specified font (or the closest possible match) as the default. When the user closes the dialog box, LogFont is filled with the selections the user made.

PointSize	int	The point size of the selected font (in tenths of a point). On input, it sets the size of the default font. On output, it returns the size the user selected.

Color	TColor	The color of the selected font, if the CF_EFFECTS flag is set. On input, it sets the color of the default font. On output, it holds the color the user selected.

Style	char far*	Lets you specify the style of the dialog.

FontType	uint16	A set of flags describing the styles of the selected font. Set only on output.

SizeMin	int	Specifies the minimum and maximum

SizeMax	int	Point sizes (in tenths of a point) the user can select, if the CF_LIMITSIZE flag is set.

In this example, a font common dialog box is used to set the window object's Font member, which is used elsewhere to paint text in the window. Note how a new font object is constructed using TFont.

void TCommDlgWnd::CmFont()

{

  TChooseFontDialog::TData FontData;

  FontData.DC = 0;

  FontData.Flags = CF_EFFECTS | CF_FORCEFONTEXIST | CF_SCREENFONTS;

  FontData.Color = Color;

  FontData.Style = 0;

  FontData.FontType = SCREEN_FONTTYPE;

  FontData.SizeMin = 0;

  FontData.SizeMax = 0;

  if (TChooseFontDialog(this, FontData).Execute() == IDOK) {

    delete Font;

    Color = FontData.Color;

    Font = new TFont(&FontData.LogFont);

  }

  Invalidate();

}


See Also

Using Color Common Dialog Boxes

Using Common Dialog Boxes

Using File Open Common Dialog Boxes

Using File Save Common Dialog Boxes

Using Find and Replace Common Dialog Boxes

Using Input Dialog Boxes

Using Printer Common Dialog Boxes


Using File Open Common Dialog Boxes (ObjectWindows)

See Also

The file-open common dialog box serves as a consistent replacement for the many different types of dialog boxes applications have used to open files.

TOpenSaveDialog::TData has several members you must initialize before constructing the dialog box object. You can either initialize them by assigning values, or you can use TOpenSaveDialog::TData's constructor, which takes the most common parameters, Flags, Filter, CustomFilter, InitialDir, and DefExt, with default arguments of zero.

TData member	Type	Description

FileName	char*	The selected file name. On input, it specifies the default file name. On output, it contains the selected file name.

Filter	char*	The file name filters and filter patterns. Each filter and filter pattern is in the form filter|filter pattern|... where filter is a text string that describes the filter and filter pattern is a DOS wildcard file name. You can repeat filter and filter pattern for as many filters as you need. You must separate them with | characters.

CustomFilter	char*	Lets you specify custom filters.

FilterIndex	int	Specifies which of the filters specified in Filter should be displayed by default.

InitialDir	char*	The directory to be displayed on opening the file dialog box. Use zero for the current directory.

DefExt	char*	Default extension appended to FileName if the user does not type an extension. If DefExt is zero, no extension is appended.

In this example, a file-open common dialog box prompts the user for a file name. If an error occurred (Execute returns IDCANCEL and Error returns nonzero), a message box is displayed.

void TCommDlgWnd::CmFileOpen()

{

  TFileOpenDialog::TData FilenameData

    (OFN_FILEMUSTEXIST | OFN_HIDEREADONLY | OFN_PATHMUSTEXIST,

    "All Files (*.*)|*.*|Text Files (*.txt)|*.txt|",

     0, "", "*");

  if (TFileOpenDialog(this, FilenameData).Execute() != IDOK) {

    if (FilenameData.Errval) {

      char msg[50];

      wsprintf(msg, "GetOpenFileName returned Error #%ld", Errval);

      MessageBox(msg, "WARNING", MB_OK | MB_ICONSTOP);

    }

  }

}


See Also

Using Color Common Dialog Boxes

Using Common Dialog Boxes

Using File Save Common Dialog Boxes

Using Find and Replace Common Dialog Boxes

Using Font Common Dialog Boxes

Using Input Dialog Boxes

Using Printer Common Dialog Boxes


Using File Save Common Dialog Boxes (ObjectWindows)

See Also

The file-save common dialog box serves as a single, consistent replacement for the many different types of dialog boxes that applications have previously used to let users choose file names.

TOpenSaveDialog::TData is used by both file-open and file-save common dialog boxes.

Example

In the following example, a file-save common dialog box prompts the user for a file name to save under. The default directory is \WINDOWS and the default extension is .BMP.

void TCanvasWindow::CmFileSaveAs()

{

  TOpenSaveDialog::TData data

    (OFN_HIDEREADONLY | OFN_OVERWRITEPROMPT,

    "Bitmap Files (*.BMP)|*.bmp|",

    0,

    "\\windows",

    "BMP");

  if (TFileSaveDialog(this, data).Execute() == IDOK) {

    // save data to file

    ifstream is(FileData->FileName);

    if (!is)

      MessageBox("Unable to open file", "File Error",

                 MB_OK | MB_ICONEXCLAMATION);

    else

      // Do file output

  }

}


See Also

Using Color Common Dialog Boxes

Using Common Dialog Boxes

Using File Open Common Dialog Boxes

Using Find and Replace Common Dialog Boxes

Using Font Common Dialog Boxes

Using Input Dialog Boxes

Using Printer Common Dialog Boxes


Using Find and Replace Common Dialog Boxes (ObjectWindows)

See Also

The find and replace common dialog boxes let you search and optionally replace text in your application's data. These dialog boxes are flexible enough to be used for documents or even databases. The simplest way to use the find and replace common dialog boxes is to use the TEditSearch or TEditFile edit control classes; they implement an edit control that you can search and replace text in. If your application is text-based, you can also use the find and replace common dialog boxes manually.

In order to use find and replace common dialog boxes, you will need to know how to:

Construct and Create Find and Replace Common Dialog Boxes

Process Find and Replace Messages

Handle a Find Next Command


See Also

Using Color Common Dialog Boxes

Using Common Dialog Boxes

Using File Open Common Dialog Boxes

Using File Save Common Dialog Boxes

Using Font Common Dialog Boxes

Using Input Dialog Boxes

Using Printer Common Dialog Boxes


Constructing and Creating Find and Replace Common Dialog Boxes (ObjectWindows)

See Also

Because the find and replace dialog boxes are modeless, you normally keep a pointer to them as a data member in your parent window object to make it easy to communicate with them.

The find and replace common dialog boxes are modeless. Construct and create them in response to a command (for example, a menu item Search|Find or Search|Replace) to display the dialog box and let the user enter the search information.

TFindReplaceDialog::TData has the standard Flags members, plus members for holding the find and replace strings.

The following example shows the pointer to the find dialog box in the parent window object and shows the command event response function that constructs and creates the dialog box:

class TDatabaseWindow : public TFrameWindow

{

    .

    .

    .

    TFindReplaceDialog::TData SearchData;

    TFindReplaceDialog* SearchDialog;

    .

    .

    .

};

void TDatabaseWindow::CmEditFind()

{

  // If the find dialog box is not already

  // constructed, construct and create it now

  if (!SearchDialog) {

    SearchData.Flags |= FR_DOWN; // default to searching down

    SearchDialog = new TFindDialog(this, SearchData)

    SearchDialog->Create();

  }

}


See Also

Processing Find and Replace Messages

Handling a Find Next Command


Processing Find and Replace Messages (ObjectWindows)

See Also

Since the find and replace common dialog boxes are modeless, they communicate with their parent window object by using a registered message FINDMSGSTRING. You must write an event response function that responds to FINDMSGSTRING. That event response function takes two parameters--a WPARAM and an LPARAM--and returns an LRESULT. The LPARAM parameter contains a pointer that you must pass to the dialog box object's UpdateData member function.

After calling UpdateData, you must check for the FR_DIALOGTERM flag. The common dialog box code sets that flag when the user closes the modeless dialog box. Your event response function should then zero the dialog box object pointer because it is no longer valid. You must construct and create the dialog box object again.

As long as the FR_DIALOGTERM flag was not set, you can process the FINDMSGSTRING message by performing the actual search. This can be as simple as an edit control object's Search member function or as complicated as triggering a search of a Paradox or dBASE table.

In this example, EvFindMsg is an event response function for a registered message. EvFindMsg calls UpdateData and then checks the FR_DIALOGTERM flag. If it was not set, EvFindMsg calls another member function to perform the search.

DEFINE_RESPONSE_TABLE1(TDatabaseWindow, TFrameWindow)

  .

  .

  .

  EV_REGISTERED(FINDMSGSTRING, EvFindMsg),

END_RESPONSE_TABLE;

.

.

.

LRESULT TDatabaseWindow::EvFindMsg(WPARAM, LPARAM lParam)

{

  if (SearchDialog) {

    SearchDialog->UpdateData(lParam);

    // is the dialog box closing?

    if (SearchData.Flags & FR_DIALOGTERM) {

      SearchDialog = 0;

      SearchCmd = 0;

    } else

      DoSearch();

  }

  return 0;

}


See Also

Constructing and Creating Find and Replace Common Dialog Boxes

Handling a Find Next Command


Handling a Find Next Command (ObjectWindows)

See Also

The find and replace common dialog boxes have a Find Next button that users can use while the dialog boxes are visible. Most applications also support a Find Next command from the Search menu, so users can find the next occurrence in one step instead of having to open the find dialog box and click the Find Next button. TFindDialog and TReplaceDialog make it easy for you to offer the same functionality.

Setting the FR_FINDNEXT flag has the same effect as clicking the Find Next button. For example,

void TDatabaseWindow::CmEditFindNext()

{

  SearchDialog->UpdateData();

  SearchData.Flags |= FR_FINDNEXT;

  DoSearch();

}


See Also

Constructing and Creating Find and Replace Common Dialog Boxes

Processing Find and Replace Messages


Using Printer Common Dialog Boxes (ObjectWindows)

See Also

There are two printer common dialog boxes. The print job dialog box lets you choose what to print, where to print it, the print quality, the number of copies, and so on. The print setup dialog box lets you choose among the installed printers on the system, the page orientation, and paper size and source.

TPrintDialog::TData's members, described in the following table, let you control the appearance and behavior of the printer common dialog boxes:

TData member	Type	Description

FromPage	int	The first page of output, if the PD_PAGENUMS flag is specified. On input, it specifies the default first page. On output, it specifies the first page the user chose.

ToPage	int	The last page of output, if the PD_PAGENUMS flag is specified. On input, it specifies the default last page number. On output, it specifies the last page number the user chose.

MinPage	int	The fewest number of pages the user can choose.

MaxPage	int	The largest number of pages the user can choose.

Copies	int	The number of copies to print. On input, the default number of copies. On output, the number of copies the user actually chose.

Example

In the following example, CmFilePrint executes a standard print job common dialog box and uses the information in TPrintDialog::TData to determine what to print. CmFilePrintSetup adds a flag to bring up the print setup dialog box automatically.

void TCanvas::CmFilePrint()

{

  if (TPrintDialog(this, data).Execute() == IDOK)

    // Use TPrinter and TPrintout to print the drawing

}

void TCanvas::CmFilePrintSetup()

{

  static TPrintDialog::TData data;

  data.Flags |= PD_PRINTSETUP;

  if (TPrintDialog(this, data, 0).Execute() == IDOK)

    // Print

}


See Also

Using Color Common Dialog Boxes

Using Common Dialog Boxes

Using File Open Common Dialog Boxes

Using File Save Common Dialog Boxes

Using Find and Replace Common Dialog Boxes

Using Font Common Dialog Boxes

Using Input Dialog Boxes

Using Printer Common Dialog Boxes


Doc/View Objects Overview (ObjectWindows)

ObjectWindows provides the Doc/View model as a way to contain and manipulate data. The Doc/View model consists of three parts:

Document objects, which can contain many different types of data and provide methods to access that data.

View objects, which form an interface between a document object and the user interface and control how the data is displayed and how the user can interact with the data.

An application-wide document manager that maintains and coordinates document objects and the corresponding view objects.

To understand more about using Doc/View objects, review the following topics:

How Documents and Views Work Together

Creating a Document Class

Creating a View Class

Doc/View Event Handling

Doc/View Properties

Document Templates

Using the Document Manager


How Documents and Views Work Together (ObjectWindows)

See Also

The Doc/View model frees the programmer and the user from worrying about what type of data a file contains and how that data is presented on the screen. Doc/View associates data file types with a document class and a view class. The document manager keeps a list of associations between document classes and view classes. Each association is called a document template (note that document templates are not related to C++ templates).

A document class handles data storage and manipulation. It contains the information that is displayed on the screen. A document object controls changes to the data and when and how the data is transferred to persistent storage (such as the hard drive, RAM disk, and so on).

When the user opens a document, whether by creating a new document or opening an existing document, the document is displayed using an associated view class. The view class manages how the data is displayed and how the user interacts with the data onscreen. In effect, the view forms an interface between the display window and the document. Some document types might have only one associated view class; others might have several. You can use different view types to let the user interact with the data in different ways.


See Also

Creating a Document Class

Creating a View Class

Doc/View Event Handling

Doc/View Objects Overview

Doc/View Properties

Document Templates

How Documents and Views Work Together

Using the Document Manager


Document Objects (ObjectWindows)
Documents (ObjectWindows)

See Also

The traditional concept of a document and the Doc/View concept of a document differ in several important ways. The traditional concept of a document is generally like that of a word-processing file: It consists of text mixed with the occasional graphic, along with embedded commands to assist the word-processing program in formatting the document.

A Doc/View document differs significantly from a traditional document.

Contents: A traditional document is mostly text with a few other bits of data, while a Doc/View document can contain literally any type of data, such as text, graphics, sounds, multimedia files, and even other documents.

Presentation: The format of a traditional document is usually designed with the document's presentation in mind, while a Doc/View document is completely independent of the way it is displayed.

Application format: A document from a particular word-processing program is generally dependent on the format demanded by that program; documents are usually portable between different word-processing programs only after a tedious porting process. Doc/View documents are intended to be application independent, so data can be easily ported between different applications, even applications whose basic functions are highly divergent.

The basic functionality for a document object is provided in the ObjectWindows class TDocument.


See Also

Associating Document and View Classes

Document Manager

View Objects


View Objects (ObjectWindows)
Views (ObjectWindows)

See Also

View objects enable document objects to present themselves to the world. Without a view object, you can't see or manipulate the document. But when you pair a document with a view object into a document template, you have a functional piece of data and code that provides both a graphic representation of the data stored in the document and a way to interact with and change that data.

The separation between the document and view also permits flexibility in when and how the data in document is modified. Although the data is manipulated through the view, the view only relays those changes on to the document. It is then up to the document to determine whether to change the data in the document (known as committing the changes) or discarding the changes (known as reverting back to the document).

Another advantage of using view objects instead of some sort of fixed display method (such as a word-processing program) is that view objects offer the programmer and the user a number of different ways to display and manipulate the same document. Although you might need to provide only one view for a document type, you might also want to provide three or four views.

For example, suppose you create a document class to store graphic information, such as a picture or drawing. For a basic product, you might want to provide only one type of view, such as a view that draws the picture in a window and then lets the user paint and modify the picture. For a more advanced version, you might want to provide extra views; for example, the drawing could be displayed as a color separation, as a hexadecimal file, or even as a series of equations if the drawing was mathematically generated. To access these other views, users choose the type of view desired when they open the document. In all these scenarios, the document itself never changes.

The basic functionality for a view is provided in the ObjectWindows class TView.


See Also

Associating Document and View Classes

Creating a View Class

Document Manager

Document Objects


Associating Document and View Classes (ObjectWindows)

See Also

A document class is associated with its view class (or classes) by a document template. Document templates are created in two steps:

1.	Define a template class that associates a document class with a view class.

2.	Instantiate a template object from a defined class.

The difference between these two steps is important. After you have defined a template class, you can create any number of instances of that template class. Each template associates only a document class and a view class. Each instance has a name, a default file extension, a directory, flags, and file filters. Thus you could provide a single template class that associates a document with a view. You could then provide a number of different instances of that template class, where each instance handles files in a different default directory, with different extensions, and so on, still using the same document and view classes.


See Also

Document Manager

Document Objects

View Objects


Document Manager (ObjectWindows)

See Also

The document manager maintains the list of template instances used in your application and the list of current documents. Every application that uses Doc/View documents must have a document manager, but each instance of an application can have only one document manager at a time.

The document manager brings the Doc/View model together: document classes, view classes, and templates. The document manager provides a default File menu and default handling for each of the following choices on the File menu:

Menu choice	Handling

New	Creates a new document.

Open...	Opens an existing document.

Save	Saves the current document.

As...	Saves the current document with a new name.

Revert To Saved	Reverts changes to the last document saved.

Close	Closes the current document.

Exit	Quits the application, prompts to save documents.

After you have written your document and view classes, defined any necessary templates, and made instances of the required templates, you need to create your document manager. When the document manager is created, it sets up its list of template instances and (if specified in the constructor) sets up its menu. Then whenever it receives one of the events that it handles, it performs the command specified for that event (see Using the Document Manager).


See Also

Associating Document and View Classes

Document Objects

View Objects

Using the Document Manager


Document Templates (ObjectWindows)

Document templates join together document classes and view classes by creating a new class. The document manager maintains a list of document templates that it uses when creating a new Doc/View instance.

Review the following topics to learn about document templates:

Designing Document Template Classes

Creating Document Registration Tables

Creating Template Class Instances

Modifying Existing Templates


Designing Document Template Classes (ObjectWindows)

See Also

You create a document template class using the DEFINE_DOC_TEMPLATE_CLASS macro. This macro takes three arguments:

Document class

View class

Template class name

The document class should be the document class you want to use for data containment. The view class should be the view class you want to use to display the data contained in the document class. The template class name should be indicative of the function of the template. It cannot be a C++ keyword (such as int, switch, and so on) or the name of any other type in the application.

For example, suppose you have two document classes--one called TPlotDocument, which contains graphics data, and another called TDataDocument, which contains numerical data. Now suppose you have four view classes, two for each document class. For TPlotDocument, you have TPlotView, which displays the data in a TPlotDocument object as a drawing, and THexView, which displays the data in a TPlotDocument object as arrays of hexadecimal numbers. For TDataDocument, you have TSpreadView, which displays the data in a TDataDocument object much like a spreadsheet, and TCalcView, which displays the data in a TDataDocument object after performing a series of calculations on the data.

To associate the document classes with their views, you would use the DEFINE_DOC_TEMPLATE_CLASS macro. The code would look something like this:

DEFINE_DOC_TEMPLATE_CLASS(TPlotDocument, TPlotView, TPlotTemplate);

DEFINE_DOC_TEMPLATE_CLASS(TPlotDocument, THexView, THexTemplate);

DEFINE_DOC_TEMPLATE_CLASS(TDataDocument, TSpreadView, TSpreadTemplate);

DEFINE_DOC_TEMPLATE_CLASS(TDataDocument, TCalcView, TCalcTemplate);

As you can see from the first line, the existing document class TPlotDocument and the existing view class TPlotView are brought together and associated in a new class called TPlotTemplate. The same thing happens in all the other lines, so that you have four new classes, TPlotTemplate, THexTemplate, TSpreadTemplate, and TCalcTemplate. The next section describes how to use these new classes you have created.


See Also

Creating Document Registration Tables

Creating Template Class Instances

Modifying Existing Templates


Creating Document Registration Tables (ObjectWindows)

See Also

After you have defined a template class, you can create any number of instances of that class. You can use template class instances to provide different descriptions of a template, search for different default file names, look in different default directories, and so on. Each of these attributes of a template class instance is affected by the document registration table passed to the template class constructor.

Document registration tables let you specify the various attributes and place them in a single object. The object type is TRegList, although in normal circumstances, you should never have to access this object directly. To create a registration table,

1.	Start your registration table definition with BEGIN_REGISTRATION. This macro takes a single parameter, the name of the registration object. This name can be whatever you want it to be, although it should be somewhat descriptive of the particular template instance you want to create with it.

2.	Register data items in the table. You can place these items in the table using the REGDATA macro. REGDATA takes two parameters. The first is a key that identifies the type of data, while the second is a string containing the actual data. The key should be a string composed of alphanumeric characters; you dont need to place quotes around this value. The actual data string can be any legal string; you do need to place quotes around this value. Also, you dont need to use commas or semicolons after the macros. There are three data items you need to enter in the table for an instance of a document template:

The description value is a short text description of the template class indicates the type of data handled by the document class and how that data is displayed by the view class.

The extension value indicates the default file extension for documents of this type.

The docfilter value indicates the file name masks that should be applied to documents when searching through file names.

3.	Register flags describing how this document type is to be opened or created. These document flags can be registered with the REGDOCFLAGS macro. REGDOCFLAGS takes a single parameter, the flags themselves. The flags specified can be one or more of the following:

Flag	Function

dtAutoDelete	Close and delete the document object when the last view is closed.

dtNoAutoView	Do not automatically create a default view.

dtSingleView	Allow only one view per document.

dtAutoOpen	Open a document upon creation.

dtHidden	Hide template from list of user selections.

4. After you have registered the necessary data items and the document mode flags, you can end the table definition with the END_REGISTRATION macro. This macro takes no parameters. You do not need to append a semicolon at the end to the line.

Example

The code below shows a sample registration table declaration. The resulting registration table is called ListReg and applies to a document template class described as a Line List, which has the default extension .PTS and the default file-name mask *.pts, is set to be automatically deleted when the last view on the document is closed, and is hidden from the list of documents available to the user.

BEGIN_REGISTRATION(ListReg)

  REGDATA(description,"Line List")

  REGDATA(extension,  ".PTS")

  REGDATA(docfilter,  "*.pts")

  REGDOCFLAGS(dtAutoDelete | dtHidden)

END_REGISTRATION


See Also

Designing Document Template Classes

Creating Template Class Instances

Modifying Existing Templates


Creating Template Class Instances (ObjectWindows)

See Also

Once you have defined a template class, you can create any number of instances of that class. You can use template class instances to provide different descriptions of a template, search for different default file names, look in different default directories, and so on. You can affect all these things when calling the template class constructor.

The signature of a template class constructor is always the same:

TplName name(TRegList& regTable);

Element	Description

TplName 	The class name you specified when defining the template class

name 	Whatever name you want to give this instance

regTable	The name of a registration table created using the BEGIN/END_REGISTRATION macros (see Creating Document Registration Tables)

Example

For example, suppose you have the following template class definition:

DEFINE_DOC_TEMPLATE_CLASS(TPlotDocument, TPlotView, TPlotTemplate);

Now suppose you want to create three instances of this template class:

One instance should have the description "Approved plots" for document files with the extension .PLT. Allow only a single view of the document and automatically delete the document when the view is closed.

Another instance should have the description "In progress" for document files with the extension .PLT. Automatically delete the document when the last view is closed.

Another instance should have the description "Proposals" for document files with the extensions .PLT or .TMP, but with the default extension of .PLT. Keep this template hidden until the user has entered a password and delete the document object when the last view is closed.

The code for these instances would look something like this:

BEGIN_REGISTRATION(aReg)

  REGDATA(description, "Approved plots",

  REGDATA(docfilter, "*.PLT",

  REGDATA(extension, "PLT",

  REGDOCFLAGS(dtSingleView | dtAutoDelete)

END_REGISTRATION

TPlotTemplate atpl(aReg);

BEGIN_REGISTRATION(bReg)

  REGDATA(description, "In progress",

  REGDATA(docfilter,"*.PLT",

  REGDATA(extension, "PLT",

  REGDOCFLAGS(dtAutoDelete);

END_REGISTRATION

TPlotTemplate btpl(bReg);

BEGIN_REGISTRATION(cReg)

  REGDATA(description, "Proposals",

  REGDATA(docfilter, "*.PLT; *.TMP",

  REGDATA(extension, "PLT",

  REGDOCFLAGS(dtHidden | dtAutoDelete);

END_REGISTRATION

TPlotTemplate *ctpl = new TPlotTemplate(cReg);

Note that, as with any other class, you can create both static and dynamic instances of a document template.


See Also

Designing Document Template Classes

Creating Document Registration Tables

Modifying Existing Templates


Modifying Existing Templates (ObjectWindows)

See Also

Once you have created an instance of a template class, you usually do not need to modify the template object. However, you might want to modify the properties with which you constructed the template by using the following access functions:

Functions	Description

GetFileFilter, 	Get and set the string used to filter file names in the current

SetFileFilter	directory.

GetDescription,	Get and set the text description of the template class.

SetDescription

GetDirectory,	Get and set the default directory.

SetDirectory

GetDefaultExt, 	Get and set the default file extension.

SetDefaultExt

GetFlags, IsFlagSet, 	Get and set the flag settings.

SetFlag, ClearFlag


See Also

Designing Document Template Classes

Creating Document Registration Tables

Creating Template Class Instances


Using the Document Manager (ObjectWindows)

See Also

The document manager, an instance of TDocManager or a TDocManager-derived class, performs a number of tasks:

Manages the list of current documents and registered templates

Handles the standard File menu command events CM_FILENEW, CM_FILEOPEN, CM_FILESAVE, CM_FILESAVEAS, CM_FILECLOSE, and optionally CM_FILEREVERT

Provides the file selection interface

To support the Doc/View model, a document manager must be attached to the application. This is done by creating an instance of TDocManager and making it the document manager for your application. The following code shows an example of how to attach a document manager to your application:

class TMyApp : public TApplication

{

  public:

    TMyApp() : TApplication() {}

    void InitMainWindow() {

      .

      .

      .

      SetDocManager(new TDocManager(dmMDI | dmMenu));

      .

      .

      .

    }

};

You can set the application document manager to a new object using the TApplication::SetDocManager function, which takes a TDocManager* and returns a pointer to the old document manager.

Note that there are two SetDocManager functions, TApplication::SetDocManager and TDocument::SetDocManager. These functions have different signatures and member functions. Do not confuse them.

The document manager's public data and functions can be accessed through the document's GetDocManager function. GetDocManager takes no parameters and returns a TDocManager&. The document manager provides the following functions for creating documents and views:

CreateAnyDoc presents all the visible templates, while the TDocTemplate member function CreateDoc presents only its own template.

CreateAnyView filters the template list for those views that support the current document and presents a list of the view names, while the TDocTemplate member function CreateView directly constructs the view specified by the document template class.

Specialized document managers can be used to support other needs. For example, an OLE 2 server needs to support class factories that create documents and views through interfaces that are not their own. If the server is invoked with the Embedded command-line flags, it doesn't bring up its own user interface and can attach a document manager that replaces the user interface with the appropriate OLE support.


See Also

Constructing the Document Manager

Creating a Document Class

Creating a View Class

Doc/View Event Handling

Doc/View Objects Overview

Doc/View Properties

Document Templates

How Documents and Views Work Together

TDocManager Event Handling


Constructing the Document Manager (ObjectWindows)

See Also

The constructor for TDocManager takes a single parameter that is used to set the mode of the document manager. You can open the document manager in one of two modes:

In single-document interface (SDI) mode, you can have only a single document open at any time. If you open a new document while another document is already open, the document manager attempts to close the first document and replace it with the new document.

In multiple-document interface (MDI) mode, you can have a number of documents and views open at the same time. Each view is contained in its own client window. Furthermore, each document can be a single document type presented by the same view class, a single document presented with different views, or even entirely different document types.

To open the document manager in SDI mode, call the constructor with the dmSDI parameter. To open the document manager in MDI mode, call the constructor with the dmMDI parameter.

There are three other parameters you can also specify:

dmMenu specifies that the document manager should install its own File menu, which provides the standard document manager File menu and its corresponding commands.

dmSaveEnabled enables the Save command on the File menu even if the document has not been modified.

dmNoRevert disables the Revert command on the File menu.

Once you have constructed the document manager you cannot change the mode.

Example

The following example shows how to open the document manager in either SDI or MDI mode. It uses command-line arguments to let the user specify whether the document manager should open in SDI or MDI mode.

class TMyApp : public TApplication {

public:

  TMyApp() : TApplication() {}

  void InitMainWindow();

  int DocMode;

  };

void TMyApp::InitMainWindow() {

  switch ((_argc > 1 && _argv[1][0]=='-' ? _argv[1][1]

                                         : (char)0) | ('S'^'s')){

    case 's': DocMode = dmSDI; break; // command line: -s

    case 'm': DocMode = dmMDI; break; // command line: -m

    default : DocMode = dmMDI; break; // no command line

  }

  SetDocManager(new TDocManager(DocMode | dmMenu));

};

If the user starts the application with the -s option, the document manager opens in SDI mode. If the user starts the application with the -m option or with no option at all, the document manager opens in MDI mode.


See Also

TDocManager Event Handling


TDocManager Event Handling (ObjectWindows)

See Also

If you specify the dmMenu parameter when you construct your TDocManager object, the document manager handles certain events on behalf of the documents. It does this by using a response table to process standard menu commands. These menu commands are provided by the document manager even when no documents are opened and regardless of whether you explicitly add the resources to your application. The File menu is also provided by the document manager. These resources are defined in the DOCVIEW.RC file, which is included by DOCVIEW.H.

The events that the document manager handles are

CM_FILECLOSE

CM_FILEOPEN

CM_FILENEW

CM_FILEREVERT

CM_FILESAVE

CM_FILESAVEAS

CM_VIEWCREATE

In some instances, you might want to handle these events yourself. Because the document manager's event table is the last to be searched, you can handle these events at the view, frame, or application level. Another option is to construct the document manager without the dmMenu parameter. You must then provide functions to handle these events, generally through the application object or your interface object.

You can still call the document manager's functions through the DocManager member of the application object. For example, suppose you want to perform some action before opening a file. Providing the function through your window class TMyWindow might look something like this:

class TMyApp : public TApplication {

public:

  TMyApp() : TApplication() {}

  void InitMainWindow();

  int DocMode;

};

void TMyApp::InitMainWindow() {

  SetMainWindow(new TMyWindow());

  // Don't specify dmMenu when constructing TDocManager

  SetDocManager(new TDocManager(dmMDI));

};

class TMyWindow : public TDecoratedMDIFrame {

public:

  TMyWindow();

  void CmFileOpen();

  /*

    You also need to provide the other event handlers

    provided by the document manager.

  */

  DECLARE_RESPONSE_TABLE(TMyWindow);

};

DEFINE_RESPONSE_TABLE1(TMyWindow, TDecoratedMDIFrame)

  EV_COMMAND(CM_FILEOPEN, CmFileOpen),

   .

   .

   .

END_RESPONSE_TABLE;

void TMyWindow::CmFileOpen() {

  // Do your extra work here.

  GetApplication()->GetDocManager()->CmFileOpen();

}


See Also

Constructing the Document Manager


Creating a Document Class (ObjectWindows)

The primary function of a document class is to provide callbacks for requested data changes in a view, to handle user actions as relayed through associated views, and to tell associated views when data has been updated. TDocument provides the framework for this functionality. The programmer needs only to add the parts needed for a specific application of the document model.

To learn more about creating a document class, review the following topics:

Constructing TDocument

Adding Functionality To Documents

Data Access Functions

Closing a Document

Expanding Document Functionality

Working with the Document Manager

Working with Views


Constructing TDocument (ObjectWindows)

See Also

TDocument is an abstract base class that cannot be directly instantiated. Therefore you implement document classes by deriving them from TDocument.

You must call TDocument's constructor when constructing a TDocument-derived class. The TDocument constructor takes only one parameter, a TDocument * that points to the parent document of the new document. If the document has no parent, you can either pass a 0 or pass no parameters; the default value for this parameter is 0.


See Also

Adding Functionality To Documents

Closing a Document

Data Access Functions

Expanding Document Functionality

Working with the Document Manager

Working with Views


Adding Functionality To Documents (ObjectWindows)

See Also

As a standard procedure, you should avoid overriding TDocument functions that are not declared virtual. The document manager addresses all TDocument-derived objects as if they were actually TDocument objects. If you override a nonvirtual function, it is not called when the document manager calls that function. Instead, the document manager calls the TDocument version of the function. But if you override a virtual function, the document manager correctly calls your class's version of the function.

The following functions are declared virtual in TDocument:

~TDocument	IsDirty

AttachStream	IsOpen

CanClose	Open

Close	OutStream

Commit	Revert

DetachStream	RootDocument

GetProperty	SetDocPath

InStream	SetTitle

You can override these functions to provide your own custom interpretation of the function. But when you do override a virtual function, be sure to find out what the base class function does. When the base class performs some sort of essential task, call the base class version of the function from your own function. For example, the base class versions of many functions perform a check of the document's hierarchy, including checking or notifying any child documents, all views, any open streams, and so on.


See Also

Closing a Document

Constructing TDocument

Data Access Functions

Expanding Document Functionality

Working with the Document Manager

Working with Views


Data Access Functions (ObjectWindows)

See Also

TDocument provides a number of functions for data access. You can access data as a simple serial stream or in whatever way you design into your derived classes. The following topics describe the helper functions you can use to control when the document attempts data access operations:

Stream Access

Stream List

Complex Data Access

Data Access Helper Functions


See Also

Adding Functionality To Documents

Closing a Document

Constructing TDocument

Expanding Document Functionality

Working with the Document Manager

Working with Views


Stream Access (ObjectWindows)

See Also

TDocument provides two functions, InStream and OutStream, that return pointers to a TInStream and a TOutStream, respectively. The TDocument versions of these function both return a 0, because the functions actually perform no actions. To provide stream access for your document class you must override these functions, construct the appropriate stream class, and return a pointer to the stream object.

TInStream and TOutStream are abstract stream classes, derived from TStream and istream or ostream, respectively. TStream provides a minimal functionality to connect the stream to a document. istream and ostream are standard C++ iostreams. You must derive document-specific stream classes from TInStream and TOutStream.

Following is a simple description of the InStream and OutStream member functions.

Both InStream and OutStream take two parameters,

XXXStream(int mode, const char far* strmId = 0);

XXX is either In or Out, mode is a stream opening mode identical to the open_mode flags used for istream and ostream, and strmId is the name of a stream source if the document supports named streams, such as a file name or device name. Passing the name of an existing data source opens a stream to or from that data source as the document's stream object. Otherwise, the object opens a new stream object.

There are also two stream-access functions called AttachStream and DetachStream. Both these functions take a reference to an existing (that is, already constructed and open) TStream-derived object. AttachStream adds the TStream-derived object to the document's list of stream objects, making it available for access. DetachStream searches the document's list of stream objects and deletes the TStream-derived object passed to it. Both these functions have protected access and thus can be called only from inside the document object.


See Also

Complex Data Access

Data Access Helper Functions

Stream List


Stream List (ObjectWindows)

See Also

Each document maintains a list of open streams that is updated as streams are added and deleted. This list is headed by the TDocument data StreamList. StreamList is a TStream * that points to the first stream in the list. If there are no streams in the list, StreamList is 0. Each TStream object in the list has a member named NextStream, which points to the next stream in the stream list.

When a new stream is opened in a document object or an existing stream is attached to the document, it is added to the document's stream list. When an existing stream is closed in a document object or detached from the document, it is removed from the document's stream list.


See Also

Complex Data Access

Data Access Helper Functions

Stream Access


Complex Data Access (ObjectWindows)

See Also

Streams can provide only simple serial access to data. In cases where a document contains multimedia files, database tables, or other complex data, you probably want more sophisticated access methods. For this purpose, TDocument uses two access functions, Open and Close, that you can override to define your own opening and closing behavior.

The TDocument version of Open performs no actions; it always returns true. You can write your own version of Open to work however you want. There are no restrictions placed on how you define opening a document. You can make it as simple as you like or as complex as necessary. Open lets you open a document and keep it open, instead of opening the document only on demand from one of the document's stream objects.

The TDocument version of Close provides a little more functionality than does Open. It checks any existing children of your document and tries to close them before closing your document. If you provide your own Close, the first thing you should do in that function is call the TDocument version of Close to ensure that all children have been closed before you close the parent document. Other than this one restriction, you are free to define the implementation of the Close function. Just as with Open, Close lets you close a document when you want it closed, as opposed to permitting the document's stream objects to close the document.


See Also

Data Access Helper Functions

Stream Access

Stream List


Data Access Helper Functions (ObjectWindows)

See Also

TDocument provides a number of functions that you can use to help protect your data:

IsDirty first checks to see whether the document itself is dirty (modified but not updated) by checking the state of the data member DirtyFlag. It then checks whether any child documents are dirty, then whether any views are dirty. IsDirty returns true if any children or views are dirty.

IsOpen checks to see whether the document is held open or has any streams in its stream list. If the document is not open, IsOpen returns false. Otherwise, IsOpen returns .

Commit commits to storage any changes to your data. Once you have called Commit, you cannot back out any changes made. The TDocument version of this function checks any child documents and commits their changes. If any child document returns false, the commit is aborted and Commit returns false. All child documents must return true before Commit commits its own data. After all child documents have returned true, Commit flushes all the views for operations that might have taken place since the document last checked the views. Data in the document is updated according to the changes in the views and then saved. Commit then returns true.

Revert performs the opposite function from Commit. Instead of updating changes and saving the data, Revert clears any changes that have been made since the last time the data was committed. Revert also polls any child documents and aborts if any of the children return false. If all operations are successful, Revert returns true.


See Also

Complex Data Access

Stream Access

Stream List


Closing a Document (ObjectWindows)

See Also

Like most other objects, TDocument provides functions that let you safely close and destroy the object.

~TDocument does a lot of cleanup. First it destroys its children and closes all open streams and other resources. Then, in order, it

1.	Detaches its attached template

2.	Closes all associated views

3.	Deletes its stream list

4.	Removes itself from its parent's list of children if the document has a parent or, if it doesn't have a parent, removes itself from the document manager's document list

In addition to a destructor, TDocument also provides a CanClose function to make sure that it's OK to close. CanClose first checks whether all its children can close. If any child returns false, CanClose returns false and aborts. If all child documents return true, CanClose calls the document manager function FlushDoc, which checks to see if the document is dirty. If the document is clean, FlushDoc and CanClose return true. If the document is dirty, FlushDoc opens a message box that prompts the user to either save the data, discard any changes, or cancel the close operation.


See Also

Adding Functionality To Documents

Constructing TDocument

Data Access Functions

Expanding Document Functionality

Working with the Document Manager

Working with Views


Expanding Document Functionality (ObjectWindows)

See Also

The TDocument class provides basic functionality for your document classes. You can expand the functionality of your document classes, for example, to add special functions for manipulating data, for understanding and acting on the information obtained from the user through a document's associated view, and so on. All this functionality goes into your TDocument-derived classes.

Because the Doc/View model is so flexible, there are no requirements or rules as to how you should approach this task. A document can handle almost any type of data because the Doc/View data-handling mechanism is a primitive framework, intended to be extended by derived classes. The base classes provided in ObjectWindows provide the functionality to support your extensions to the Doc/View model.


See Also

Adding Functionality To Documents

Closing a Document

Constructing TDocument

Data Access Functions

Working with the Document Manager

Working with Views


Working with the Document Manager (ObjectWindows)

See Also

TDocument provides two functions for accessing the document manager, GetDocManager and SetDocManager.

GetDocManager returns a pointer to the current document manager. You can then use this pointer to access the data and function members of the document manager.

SetDocManager lets you assign the document to a different document manager.

All other document manager functionality is contained in the document manager itself.


See Also

Adding Functionality To Documents

Closing a Document

Constructing TDocument

Data Access Functions

Expanding Document Functionality

Working with Views


Working with Views (ObjectWindows)

See Also

TDocument provides two functions for working with views, NotifyViews and QueryViews. Both functions take three parameters, an int corresponding to an event, a long item, and a TView *. The meaning of the long item is dependent on the event and is essentially a parameter to the event. The TView * lets you exclude a view from your query or notification by passing a pointer to that view to the function. These two functions are your primary means of communicating information between your document and its views.

Both functions call views through the views' response tables. The general-purpose macro used for ObjectWindows notification events is EV_OWLNOTIFY. The response functions for EV_OWLNOTIFY events have the following signature:

bool FnName(long);

The long item used in the NotifyViews or QueryViews function call is used for the long parameter for the response function.

You can use NotifyViews to notify your child documents, their associated views, and the associated views of your root document of a change in data, an update, or any other event that might need to be reflected onscreen. The meaning of the event and the accompanying item passed as a parameter to the event are implementation defined.

NotifyViews first calls all the document's child documents' NotifyViews functions, which are called with the same parameters. After all the children have been called, NotifyViews passes the event and item to all of the document's associated views. NotifyViews returns a bool. If any child document or associated view returns false, NotifyViews returns false. Otherwise NotifyViews returns true.

QueryViews sends an event and accompanying parameter just like NotifyViews. The difference is that, whereas NotifyViews returns true when any child or view returns true, QueryViews returns a pointer to the first view that returns true. This behavior makes QueryViews useful for finding a view that meets some condition and then performing some action on that view. If no views return true, QueryViews returns 0.

Another difference between NotifyViews and QueryViews is that NotifyViews always sends the event and its parameter to all children and associated views, while QueryViews stops at the first view that returns true.

Example

Suppose you have a document class that contains graphics data in a bitmap. You want to know which of your associated views is displaying a certain area of the current bitmap. You can define an event such as WM_CHECKRECT. Then you can set up a TRect structure containing the coordinates of the rectangle you want to check for. The excerpted code would look something like this:

DEFINE_RESPONSE_TABLE1(TMyView, TView)

   .

   .

   .

  EV_OWLNOTIFY(WM_CHECKREST, EvCheckRest),

   .

   .

   .

END_RESPONSE_TABLE;

void MyDocClass::Function() {

  // Set up a TRect * with the coordinates you want to send.

  TRect *rect = new TRect(100, 100, 300, 300);

  // QueryViews

  TView *view = QueryViews(WM_CHECKRECT, (long) rect);

  // Clear all changes from the view

  if(view)

    view->Clear();

}

// The view response function gets the pointer to the rectangle

// as the long parameter to its response function.

bool TMyView::EvCheckRest(long item) {

  TRect *rect = (TRect *) item;

  // Check to see if rect is equal to this view's rect.

  if(*rect == this->rect)

    return true;

  else

    return false;

}

You can also set up your own event macros to handle view notifications, as described in Doc/View Event Handling.


See Also

Adding Functionality To Documents

Closing a Document

Constructing TDocument

Data Access Functions

Expanding Document Functionality

Working with the Document Manager


Creating a View Class (ObjectWindows)

See Also

The user almost never interacts directly with a document. Instead the user works with an interface object, such as a window, a dialog box, or whatever type of display is appropriate for the data being presented and the method in which it is presented. But this interface object doesn't stand on its own. A window has no information about the data it displays, the document that contains that data, or about how the user can manipulate and change the data. All this functionality is handled by the view object.

A view forms an interface between an interface object (which can only do what it is told to do) and a document (which does not know how to tell the interface object what to do). The view's job is to bridge the gap between the two objects, reading the data from the document object and telling the interface object how to display that data.

The following topics describe how to write a view class to work with your document classes:

Constructing TView

Adding Functionality To Views

Adding a Display To a View

Closing a View


See Also

Creating a Document Class

Doc/View Event Handling

Doc/View Objects Overview

Doc/View Properties

Document Templates

How Documents and Views Work Together

Using the Document Manager


Constructing TView (ObjectWindows)

You cannot directly create an instance of TView. TView contains a number of pure virtual functions and placeholder functions whose functionality must be provided in any derived classes. But you must call the TView constructor when you are constructing your TView-derived object. The TView constructor takes one parameter, a reference to the view's associated document. You must provide a valid reference to a TDocument-derived object.


See Also

Creating A View Class

Adding a Display To a View

Adding Functionality To Views

Closing a View


Adding Functionality To Views (ObjectWindows)

See Also

TView contains some pure virtual functions that you must provide in every new view class. It also contains a few placeholder functions that have no base class functionality. You need to provide new versions of these functions if you plan to use them for anything.

Much like TDocument, you should not override a TView function unless that function is a virtual. When functions in TDocument call functions in your view, they address the view object as a TView. If you override a nonvirtual function and the document calls that function, the document actually calls the TView version of that function, rendering your function useless in that context.

TView Virtual Functions (ObjectWindows)

The following functions are declared virtual so you can override them to provide some useful functionality. But most are not declared as pure virtuals; you are not required to override them to construct a view. Instead, you need to override these functions only if you plan to use them.

GetViewName returns the static name of the view. This function is declared as a pure virtual function; you must provide a definition of this function in your view class.

GetWindow returns a TWindow * that should reference the view's associated interface object if it has one; otherwise, GetWindow returns 0.

SetDocTitle sets the view window's caption. It should be set to call the SetDocTitle function in the interface object.

Adding a Menu (ObjectWindows)

TView contains the private TMenuDescr * data member ViewMenu. You can assign any existing TMenuDescr object to this member. Normally you set the menu up in the view's constructor to make it merge with the frame window's menu when the view is activated.


See Also

Creating A View Class

Adding a Display To a View

Closing a View

Constructing TView


Adding a Display To a View (ObjectWindows)

See Also

TView itself makes no provision for displaying data--it has no pointer to a window, no graphics functions, no text display functions, and no keyboard handling. To provide this functionality in your derived classes, use one of the following methods:

Adding a pointer to an interface object in your derived view class

Mixing TView with interface objects when deriving your new view class

Each of these methods has its advantages and drawbacks. Weigh the pros and cons of each approach before deciding how to build your view class.


See Also

Creating A View Class

Adding Functionality To Views

Closing a View

Constructing TView


Adding Pointers To Interface Objects (ObjectWindows)

To add a pointer to an interface object to your TView-derived class, add the member to the new class and instantiate the object in the view class's constructor. Access to the interface object's data and function members is through the pointer.

The advantage of this method is that it lets you easily attach and detach different interface objects. It also lets you use different types of interface objects by making the pointer a pointer to a common base class of the different objects you might want to use. For example, you can use most kinds of interface objects by making the pointer a TWindow *.

The disadvantage of this method is that event handling must go through either the interface object or the application first. This basically forces you to either use a derived interface object class to add your own event-handling functions that make reference to the view object, or handle the events through the application object. Either way, you decrease your flexibility in handling events.


See Also

Adding a Display To a View

Mixing TView with Interface Objects


Mixing TView with Interface Objects (ObjectWindows)

See Also

Mixing TView or a TView-derived object with an interface object class gives you the ability to display data from a document and makes that ability integral with handling the flow of data to and from the document object. To mix a view class with an interface object class is a fairly straightforward task, but one that must be undertaken with care.

To derive your new class, define the class based on your base view class (TView or a TView-derived class) and the selected interface object. The new constructor should call the constructors for both base classes and initialize any data that needs to be set up. At a bare minimum, the new class must define any functions that are declared pure virtual in the base classes. It should also define functions for whatever specialized screen activities it needs to perform and define event-handling functions to communicate with both the interface element and the document object.

The advantage of this approach is that the resulting view is highly integrated. Event handling is performed in a central location, reducing the need for event handling at the application level. Control of the interface elements does not go through a pointer but is also integrated into the new view class.

The disadvantage of this approach is that you lose the flexibility you have with a pointer. You cannot quickly detach and attach new interface objects because the interface object is an organic part of the whole view object. You also cannot exchange different types of objects by using a base pointer to a different interface object classes. Your new view class is locked into a single type of interface element.


See Also

Adding a Display To a View

Adding Pointers To Interface Objects


Closing a View (ObjectWindows)

See Also

Like most other objects, TView provides functions that let you safely close and destroy the object.

~TView does fairly little. It calls its associated document's DetachView function, thus removing itself from the document's list of views.

TView also provides a CanClose function, which calls its associated document's CanClose function. Therefore the view's ability to close depends on the document's ability to close.


See Also

Adding a Display To a View

Adding Functionality To Views

Constructing TView


Doc/View Event Handling (ObjectWindows)

See Also

You normally handle Doc/View events through both the application object and your view's interface element. You can either control the view's display through a pointer to an interface object or mix the functionality of the interface object with a view class. (See Mixing TView with Interface Objects.)

To understand more about Doc/View event handling, review the following topics:

Doc/View Event Handling in the Application Object

Doc/View Event Handling in a View


See Also

Creating a Document Class

Creating a View Class

Doc/View Objects Overview

Doc/View Properties

Document Templates

How Documents and Views Work Together

Using the Document Manager


Doc/View Event Handling in the Application Object (ObjectWindows)

See Also

The application object generally handles only a few events, indicating when a document or a view has been created or destroyed. The dnCreate event is posted whenever a view or document is created. The dnClose event is posted whenever a view or document is closed.

To set up response table entries for these events, add the EV_OWLDOCUMENT and EV_OWLVIEW macros to your response table as follows:

Use the EV_OWLDOCUMENT macro to check for

The dnCreate event when a new document object is created. The standard name used for the handler function is EvNewDocument. EvNewDocument takes a reference to the new TDocument-derived object and returns void.

The dnClose event when a document object is about to be closed. The standard name used for the handler function is EvCloseDocument. EvCloseDocument takes a reference to the TDocument-derived object that is being closed and returns void.

The response table entries and function declarations for these two macros would look like this:

DEFINE_RESPONSE_TABLE1(MyDVApp, TApplication)

  .

  .

  .

  EV_OWLDOCUMENT(dnCreate, EvNewDocument),

  EV_OWLDOCUMENT(dnClose, EvCloseDocument),

  .

  .

  .

END_RESPONSE_TABLE;

void EvNewDocument(TDocument& document);

void EvCloseDocument(TDocument& document);

Use the EV_OWLVIEW macro to check for

The dnCreate event when a new view object is constructed. The standard name used for the handler function is EvNewView. EvNewView takes a reference to the new TView-derived object and returns void.

If the view contains a window interface element, either by inheritance or through a pointer, the interface element typically has not been created when the view is constructed. You can then modify the interface element's creation attributes before actually calling the Create function.

The dnClose event when a view object is destroyed. The standard name used for the handler function is EvCloseView. EvCloseView takes a reference to the TView-derived object that is being destroyed and returns void.

The response table entries and function declarations for these two macros would look like this:

DEFINE_RESPONSE_TABLE1(MyDVApp, TApplication)

  .

  .

  .

  EV_OWLVIEW(dnCreate, EvNewView),

  EV_OWLVIEW(dnClose, EvCloseView),

  .

  .

  .

END_RESPONSE_TABLE;

void EvNewView(TView &view);

void EvCloseView(TView &view);


See Also

Doc/View Event Handling

Doc/View Event Handling in a View


Doc/View Event Handling in a View (ObjectWindows)

See Also

The header file docview.h provides a number of response table macros for predefined events, along with the handler function names and type checking for the function declarations. You can also define your own events and functions to handle those events using the NOTIFY_SIG and VN_DEFINE macros.

To understand more about event handling in a view, review the following topics:

Handling Predefined Doc/View Events

Adding Your Own View Events


See Also

Doc/View Event Handling

Doc/View Event Handling in the Application Object


Handling Predefined Doc/View Events (ObjectWindows)

See Also

There are a number of predefined Doc/View events. Each event has a corresponding response table macro and handler function signature defined. Note that the Doc/View model doesn't provide versions of these functions. You must declare the functions in your view class and provide the appropriate functionality for each function.

Response table macro	Event name	Event handler	Event

EV_VN_VIEWOPENED	vnViewOpened	VnViewOpened(TView *)	Indicates that a new view has been constructed.

EV_VN_VIEWCLOSED	vnViewClosed	VnViewClosed(TView *)	Indicates that a view is about to be destroyed.

EV_VN_DOCOPENED	vnDocOpened	VnDocOpened(int)	Indicates that a new document has been opened.

EV_VN_DOCCLOSED	vnDocClosed	VnDocClosed(int)	Indicates that a document has been closed.

EV_VN_COMMIT	vnCommit	VnCommit(bool)	Indicates that changes made to the data in the view should be committed to the document.

EV_VN_REVERT	vnRevert	VnRevert(bool)	Indicates that changes made to the data in the view should be discarded and the data should be restored from the document.

EV_VN_ISDIRTY	vnIsDirty	VnIsDirty(void)	Should return true if changes have been made to the data in the view and not yet committed to the document, otherwise returns false.

EV_VN_ISWINDOW	vnIsWindow	VnIsWindow(HWND)	Should return true if the HWND parameter is the same as that of the view's display window.

All the event-handling functions used for these messages return bool.


See Also

Doc/View Event Handling in a View

Adding Your Own View Events


Adding Your Own View Events (ObjectWindows)

See Also

You can use the VN_DEFINE and NOTIFY_SIG macros to post your own custom view events and to define corresponding response table macros and event-handling functions. This section describes how to define an event and set up the event-handling function and response table macro for that event.

First you must define the name of the event you want to handle. By convention, this name should begin with the letters vn followed by the event name. A custom view event should be defined as a const int greater than the value vnCustomBase. You can define your event values as being vnCustomBase plus some offset value. For example, suppose you are defining an event called vnPenChange. The code would look something like this:

const int vnPenChange = vnCustomBase + 1;

Next use the NOTIFY_SIG macro to specify the signature of the event-handling function. The NOTIFY_SIG macro takes two parameters: the event name and the exact parameter type to be passed to the function. The size of this parameter can be no larger than type long; if the object being passed is larger than a long, you must pass it by pointer. For example, suppose for the vnPenChange event, you want to pass a TPen object to the event-handling function. Because a TPen object is quite a bit larger than a long, you must pass the object by pointer. The macro would look something like this:

NOTIFY_SIG(vnPenChange, TPen *)

Now you need to define the response table macro for your event. By convention, the macro name uses the event name, in all uppercase letters, preceded by EV_VN_. Use the #define macro to define the macro name. Use the VN_DEFINE macro to define the macro itself. This macro takes three parameters:

Event name

Event-handling function name (by convention, the same as the event name preceded by Vn instead of the vn used for the event name)

Size of the parameter for the event-handling function; this can have four different values:

void

int (size of an int parameter depends on the platform)

long (32-bit integer or far pointer)

pointer (size of a pointer parameter depends on the memory model)

Specify the value that most closely corresponds to the event-handling function's parameter type.

The definition of the response table macro for the vnPenChange event would look something like this:

#define EV_VN_PENCHANGE \

  VN_DEFINE(vnPenChange, VnPenChange, pointer)

Note:	The third parameter of the VN_DEFINE macro in this case is pointer. It indicates the size of the value passed to the event-handling function.


See Also

Doc/View Event Handling in a View

Handling Predefined Doc/View Events


Doc/View Properties (ObjectWindows)

See Also

Every document and view object contains a list of properties, along with functions you can use to query and change those properties. The properties contain information about the object and its capabilities. When the document manager creates or destroys a document or view object, it sends a notification event to the application. The application can query the object's properties to determine how to proceed. Views can also access the properties of their associated document.


See Also

Creating a Document Class

Creating a View Class

Doc/View Event Handling

Doc/View Objects Overview

Doc/View Properties

Document Templates

How Documents and Views Work Together

Using the Document Manager


Property Values and Names (ObjectWindows)

See Also

TDocument and TView each have some general properties. These properties are available in any classes derived from TDocument and TView. These properties are indexed by a list of enumerated values. The first property for every TDocument- and TView-derived class should be PrevProperty. The last value in the property list should be NextProperty. These two values delimit the property list of every document and view object. They ensure that your property list starts at the correct value and does not overstep another property's value, and they allow derived classes to ensure that their property lists start at a suitable value. PrevProperty should be set to the value of the most direct base class's NextProperty - 1.

For example, a property list for a class derived from TDocument might look something like this:

enum {

  PrevProperty = TDocument::NextProperty-1,

  Size,

  StorageSize,

  NextProperty,

};

Note:	Use the scope operator (::) when setting PrevProperty to ensure that you set it to the correct value for NextProperty.

Property names are usually contained in an array of strings, with the position of each name in the array corresponding to its enumerated property index. However, when adding properties to a derived class, you can store and access the strings in any style you want. Because you have to write the functions to access the properties, complicated storage schemes aren't recommended. A property name should be a simple description of the property.

Property attributes are likewise usually contained in an array (of int). You can set up the array any way you like, but the usual practice is to have the attributes for a property contained in an array corresponding to the value of its property index.


See Also

Accessing Property Information


Accessing Property Information (ObjectWindows)

See Also

There are a number of functions provided in both TDocument and TView for accessing Doc/View object property information. All these functions are declared virtual. Because the property access functions are virtual, the function in the most derived class gets called first, and can override properties defined in a base class. It is the responsibility of each class to implement property access and to resolve its property names.

You normally access a property by its index number. Use the FindProperty function with the property name. FindProperty takes a char * parameter and searches the property list for a property with the same name. It returns an int, which is used as the property index for succeeding calls.

You can also use the PropertyName function to find the property name from the index. PropertyName takes an int parameter and returns a char * containing the name of the property.

You can get the attributes of a property using the PropertyFlags function. This function takes an int parameter, the index of the desired property, and returns an int. You can determine whether a flag is set by using the & operator. For example, to determine whether you can get a property value in text form, you can check to see whether the pfGetText flag is set, as follows:

if(doc->PropertyFlags() & pfGetText) {

  // Get property as text....

}


See Also

Getting and Setting Properties

Property Values and Names


Getting and Setting Properties (ObjectWindows)

You can use the GetProperty and SetProperty functions to query and modify the values of a Doc/View object's properties.

The GetProperty function lets you find out the value of a property. Its syntax is

int GetProperty(int index, void far* dest, int textlen = 0);

GetProperty parameters

Parameter	Description

index	Property index.

dest 	Used by GetProperty to contain the property data.

textlen 	Indicates the size of the memory array pointed to by dest. If textlen is 0, the property data is not returned; instead, GetProperty returns 0. Otherwise the data is returned in a textlen size buffer.

The SetProperty function lets you set the value of a property. Its syntax is

bool SetProperty(int index, const void far* src)

SetProperty parameters

Parameter	Description

index	Property index

src 	Contains the data to which the property is being set. src must be in the correct native format for the property.

{

A derived class that duplicates property names should use the same behavior and data type for the duplicate properties as they had in the parent class.


Control Objects Overview (ObjectWindows)

Controls are standard user-interface elements with specialized behavior (for example, pushbuttons). In addition to the standard controls provided by Windows, ObjectWindows provides a number of custom controls. ObjectWindows supplies interface objects for controls so you can use controls in your applications. Interface objects for controls are called control objects.

This section covers the following topics:

Tasks common to all control objects

Control Classes

What Are Control Objects?

Constructing and destroying control objects

Constructing and Destroying Control Objects

Communicating with control objects

Communicating with Control Objects

Using each of the different control objects

Using Particular Controls

Setting and reading control values

Setting and Reading Control Values


Control Classes (ObjectWindows)

The following table lists all the control classes ObjectWindows provides.

Controls and their ObjectWindows classes

Control	Class name	Description

Standard Windows controls:

List box	TListBox	A list of items to choose from.

Scroll bar	TScrollBar	A scroll bar (like those in scrolling windows and list boxes) with direction arrows and an elevator thumb.

Button	TButton	A button with an associated text label.

Check box	TCheckBox	A button consisting of a box that can be checked (on) or unchecked (off), with an associated text label.

Radio button	TRadioButton	A button that can be checked (on) or unchecked (off), usually in mutually exclusive groups.

Group box	TGroupBox	A static rectangle with optional text in the upper-left corner.

Edit control	TEdit	A field for the user to type text in.

Static control	TStatic	Visible text the user cannot change.

Combo box	TComboBox	A combined list box and edit or static control.

Custom ObjectWindows controls:

Slider	THSlider and	Horizontal and vertical controls

TVSlider	that let the user choose from an upper and lower range (similar to scroll bars).

Gauge	TGauge	Static controls that display a range of process completion.

Control object sample programs can be found in EXAMPLES\OWL\OWLAPI and EXAMPLES\OWL\OWLAPPS.


What Are Control Objects? (ObjectWindows)

To Windows, controls are just specialized windows. In ObjectWindows, TControl is derived from TWindow.

Control objects and window objects are similar in how they behave as child windows, and in how you create and destroy them. Standard controls differ from other windows, however, in that Windows handles their event messages and is responsible for painting them. Custom ObjectWindows controls handle these tasks themselves because the ObjectWindows control classes contain the code needed to paint the controls and handle events.

In many cases, you can directly use instances of control classes. However, sometimes you might need to create derived classes for specialized behavior. For example, you might derive a specialized list box class from TListBox called TFontListBox that holds the names of all the fonts available to your application and automatically displays them when you create an instance of the class.


Constructing and Destroying Control Objects (ObjectWindows)

See Also

Regardless of the type of control object you're using, there are several tasks you need to perform for each:

Constructing the control object

Showing the control

Destroying the control

Constructing Control Objects

Constructing a control object is no different from constructing any other child window. Generally, the parent window's constructor calls the constructors of all its child windows.

Controls communicate with parent windows in special ways (called notifications) in addition to the usual links between parent and child.

To construct and initialize a control object:

1.	Add a control object pointer data member to the parent window.

2.	Call the control object's constructor.

3.	Change any control attributes.

4.	Initialize the control in SetupWindow.

Showing Controls

It is not necessary to call the Windows function Show to display controls. Controls are child windows, and Windows automatically displays and repaints them along with the parent window. You can use Show, however, to hide or reveal controls on demand.

Destroying the Control

Destroying controls is the parent window's responsibility. The control's interface element is automatically destroyed along with the parent window when the user closes the window or application. The parent window's destructor automatically destroys its child window objects (including child control objects).


See Also

Adding the Control Object Pointer Data Member

Calling Control Object Constructors

Changing Control Attributes

Initializing the Control


Adding the Control Object Pointer Data Member (ObjectWindows)

See Also

Often when you construct a control in a window, you want to keep a pointer to the control in a window object data member. This is for convenience in accessing the control's member functions. Here's a fragment of a parent window object with the declaration for a pointer to a button control object:

class TMyWindow : public TWindow {

   TButton *OkButton;

   ...

   };

Controls that you rarely manipulate, like static text and group boxes, do not need these pointer data members. The following example constructs a group box without a data member and a button with a data member (OkButton):

TMyWindow::TMyWindow(TWindow *parent, const char far *title)

          :TWindow(parent, title)

{

  new TGroupBox(this, ID_GROUPBOX, "Group box", 10, 10, 100, 100);

  OkButton = new TButton(this, IDOK, "OK", 10, 200, 50, 50, true);

}


See Also

Calling Control Object Constructors

Changing Control Attributes

Initializing the Control


Calling Control Object Constructors (ObjectWindows)

See Also

Some control object constructors are passed parameters that specify characteristics of the control object. These parameters include

A pointer to the parent window object

A resource identifier

The x-coordinate of the upper-left corner

The y-coordinate of the upper-left corner

The width

The height

Optional module pointer

For example, one of TListBox's constructors is declared as follows:

TListBox(TWindow *parent, int resourceID,

         int x, int y, int w, int h,

         TModule *module = 0);

There are also constructors for associating a control object with an interface element (for example a dialog box) created from a resource definition:

TListBox(TWindow* parent, int resourceId, TModule* module = 0);


See Also

Adding the Control Object Pointer Data Member

Changing Control Attributes

Initializing the Control


Changing Control Attributes (ObjectWindows)

See Also

All control objects get the default window styles WS_CHILD, WS_VISIBLE, WS_GROUP, and WS_TABSTOP. If you want to change a control's style, you manipulate its Attr.Style. Each control type also has other styles that define its particular properties.

Each control object inherits certain window styles from its base classes. You should rarely assign a value to Attr.Style. Instead, you should use the bitwise assignment operators (|= and &=) to mask in or mask out the window style you want. For example:

// mask in the WS_BORDER window style

Attr.Style |= WS_BORDER;

// mask out the WS_VSCROLL style

Attr.Style &= ~WS_VSCROLL;

Using the bitwise assignment operators helps ensure that you do not inadvertently remove a style.


See Also

Adding the Control Object Pointer Data Member

Calling Control Object Constructors

Initializing the Control


Initializing the Control (ObjectWindows)

See Also

A control object's interface element is automatically created by the SetupWindow member function inherited by the parent window object. Make sure that when you derive new window classes, you call the base class's SetupWindow member function before attempting to manipulate its controls (for example, by calling control object member functions, sending messages to those controls, and so on).

You must not initialize controls in their parent window object's constructor. At that time, the controls' interface elements have not yet been created.

Here's a typical SetupWindow:

void TMyWindow::SetupWindow()

{

  TWindow::SetupWindow();    //Lets TWindow create any child controls

  list1->AddString("Item 1");

  list1->AddString("Item 2");

}


See Also

Adding the Control Object Pointer Data Member

Calling Control Object Constructors

Changing Control Attributes


Communicating with Control Objects (ObjectWindows)

See Also

Communication between a window object and its control objects is similar in some ways to the communication between a dialog box object and its controls. Like a dialog box, a window needs a mechanism for manipulating its controls and for responding to control events, such as a list box selection.


See Also

Manipulating Controls (ObjectWindows)

Making a Window Act Like a Dialog Box


Manipulating Controls (ObjectWindows)

See Also

One way dialog boxes manipulate their controls is by sending them messages using member functions inherited from TWindow, with a control message like LB_ADDSTRING.

Control objects greatly simplify this process by providing member functions that send control messages for you. TListBox::AddString, for example, takes a string as its parameter and adds it to the list box by calling the list box object's HandleMessage member function:

int TListBox::AddString(const char far* str)

{

  return (int)HandleMessage(LB_ADDSTRING, 0, (LPARAM)str);

}

This example shows how you can call the control objects' member functions via a pointer:

ListBox1->AddString("Atlantic City"); //ListBox1 is a TListBox *


See Also

Making a Window Act Like a Dialog Box


Making a Window Act Like a Dialog Box (ObjectWindows)

See Also

A dialog box lets the user use the Tab key to cycle through all of the dialog box's controls. It also lets the user use the arrow keys to select radio buttons in a group box. To emulate this keyboard interface for windows with controls, call EnableKBHandler in the window object's constructor.


See Also

Manipulating Controls (ObjectWindows)


Using Particular Controls (ObjectWindows)

Each type of control operates somewhat differently from the others. The following topics describe how to use the objects for each of the standard Windows controls and the custom controls supplied with ObjectWindows.

Working with standard controls

Using List Box Controls

Constructing Static Control Objects

Constructing Buttons

Using Check Box and Radio Button Controls

Modifying Selection Boxes

Constructing Group Boxes

Using Scroll Bars

Avoiding Thumb Tracking Messages

Specializing Scroll Bar Behavior

Using Sliders and Gauges

Using Edit Controls

Using Combo Boxes

Using Transfer Buffers

List Box Transfer

Combo Box Transfer


Using List Box Controls (ObjectWindows)

See Also

Using a list box is the simplest way to ask the user to pick something from a list. The TListBox class encapsulates list boxes. TListBox defines member functions for four purposes:

Creating list boxes

Modifying the list of items

Inquiring about the list of items

Finding out which item the user selected


See Also

Constructing List Box Objects

Modifying List Boxes

Querying List Boxes

Responding To List Boxes


Constructing List Box Objects (ObjectWindows)

See Also

One of TListBox's constructors takes seven parameters: a parent window, a resource identifier, the control's x, y, h, and w dimensions, and an optional module pointer, as shown in the following syntax statement:

TListBox(TWindow *parent, int resourceId, int x, int y, int w, int h, TModule *module = 0);

TListBox gets the default control styles (WS_CHILD, WS_VISIBLE, WS_GROUP, and WS_TABSTOP) and adds LBS_STANDARD, which is a combination of LBS_NOTIFY (to receive notification messages), WS_VSCROLL (to have a vertical scroll bar), LBS_SORT (to sort the list items alphabetically), and WS_BORDER (to have a border). If you want a different list box style, you can modify Attr.Style in the list box object's constructor or in its parent's constructor.

For example, for a list box that does not sort its items, use the following code:

listbox = new TListBox(this, ID_LISTBOX, 20, 20, 340, 100);

listbox->Attr.Style &= ~LBS_SORT;


See Also

Using List Box Controls

Modifying List Boxes

Querying List Boxes

Responding To List Boxes


Modifying List Boxes (ObjectWindows)

See Also

After you create a list box, you need to fill it with list items (which must be strings). Later, you can add, insert, or remove items or clear the list completely. The following table summarizes the member functions you use to perform these actions.

TListBox member functions for modifying list boxes

Member function	Description

ClearList	Delete every item.

DirectoryList	Put file names in the list.

AddString	Add an item.

InsertString	Insert an item.

DeleteString	Delete an item.

SetSelIndex, SetSel, or	Select an item.

SetSelString

SetSelStrings, SetSelIndexes, or	Select multiple items.

SetSelItemRange

SetTopIndex	Scroll the list box so the specified item is visible.

SetTabStops	Set tab stops for multicolumn list boxes.

SetHorizontalExtent	Set number of pixels by which the list box can scroll horizontally.

SetColumnWidth	Set width of all columns in multicolumn list boxes.

SetCaretIndex	Set index of the currently focused item.

SetItemData	Set a uint32 value to be associated with the specified index.

SetItemHeight	Set the height of item at the specified index or height of all items.


See Also

Using List Box Controls

Constructing List Box Objects

Querying List Boxes

Responding To List Boxes


Querying List Boxes (ObjectWindows)

See Also

There are several TListBox member functions you can call to find out information about the list box or its item list. The following table summarizes the list box query member functions.

TListBox member functions for querying list boxes

Member functions	Description

GetCount	Number of items in the list.

FindString or FindExactString	Find string index.

GetTopIndex	Index of the item at the top of the list box.

GetCaretIndex	Index of the currently focused item.

GetHorizontalExtent	Number of pixels the list box can scroll horizontally.

GetItemData	uint32 data set by SetItemData.

GetItemHeight	Height, in pixels, of the specified item.

GetItemRect	Rectangle used to display the specified item.

GetSelCount	Number of selected items (either 0 or 1).

GetSelIndex or GetSel	Index of the selected item.

GetSelString	Selected item.

GetSelStrings or GetSelIndexes	Selected items.

GetString	Item at a particular index.

GetStringLen	Length of a particular item.


See Also

Using List Box Controls

Constructing List Box Objects

Modifying List Boxes

Responding To List Boxes


Responding To List Boxes (ObjectWindows)

See Also

The member functions for modifying and querying list boxes let you set values or find out the status of the control at any given time. To know what a user is doing to a list box at run time, however, you have to respond to notification messages from the control.

There are only a few things a user can do with a list box: scroll through the list, click an item, and double-click an item. When the user does one of these things, Windows sends a list box notification message to the list box's parent window. Normally, you define notification-response member functions in the parent window object to handle notifications for each of the parent's controls.

The following table summarizes the most common list box notifications:

List box notification messages

Event response table macro	Description

EV_LBN_SELCHANGE	An item has been selected with a single mouse click.

EV_LBN_DBLCLK	An item has been selected with a double mouse click.

EV_LBN_SELCANCEL	The user has deselected an item.

EV_LBN_SETFOCUS	The user has given the list box the focus by clicking or double-clicking an item, or by using Tab. Precedes LBN_SELCHANGE notification.

EV_LBN_KILLFOCUS	The user has removed the focus from the list box by clicking another control or pressing Tab.

Here is a sample parent window object member function to handle an LBN_SELCHANGE notification:

DEFINE_RESPONSE_TABLE1(TLBoxWindow, TFrameWindow)

  EV_LBN_SELCHANGE(ID_LISTBOX, EvListBoxSelChange),

END_RESPONSE_TABLE;

void TLBoxWindow::EvListBoxSelChange()

{

  int index = ListBox->GetSelIndex();

  if (ListBox->GetStringLen(index) < 10) {

    char string[10];

    ListBox->GetSelString(string, sizeof(string));

    MessageBox(string, "You selected:", MB_OK);

  }

}


See Also

Using List Box Controls

Constructing List Box Objects

Modifying List Boxes

Querying List Boxes


Constructing Static Control Objects (ObjectWindows)

See Also

Static controls are usually unchanging units of text or simple graphics. The user does not interact with static controls, although your application can change the static control's text.

See EXAMPLES\OWL\OWLAPI\STATIC for an example showing static controls.

Because the user never interacts directly with a static control, the application does not receive control-notification messages from static controls. Therefore, you can construct most static controls with -1 as the control ID. However, if you want to use TWindow::SendDlgItemMessage to manipulate the static control, you need a unique ID.

One of TStatic's constructors is declared as follows:

TStatic(TWindow* parent,

        int resourceId,

        const char far* title,

        int x, int y, int w, int h,

        UINT textLen = 0,

        TModule* module = 0);

It takes the seven parameters commonly found in this form of a control object constructor (a parent window, a resource ID, the control's x, y, h, and w dimensions, and an optional module pointer), and two parameters specific to static controls: the text string the static control displays and its maximum length (including the terminating NULL). A typical call to construct a static control looks like this:

new TStatic(this, -1, "Sample &Text", 170, 20, 200, 24);

If you want to be able to change the static control's text, you need to assign the control object to a data member in the parent window object so you can call the static control object's member function. If the static control's text does not need to change, you do not need a data member.

TStatic gets the default control styles (WS_CHILD, WS_VISIBLE, WS_GROUP, and WS_TABSTOP), adds SS_LEFT (to left-align the text), and removes the WS_TABSTOP style (to prevent the user from selecting the control using Tab). To change the style, modify Attr.Style in the static control object's constructor. For example, the following code centers the control's text:

Attr.Style = (Attr.Style & ~SS_LEFT) | SS_CENTER;

To indicate a mnemonic for a nearby control, you can underline one or more characters in the static control's text string. To do this, insert an ampersand (&) in the string immediately preceding the character you want underlined. For example, to underline the T in Text, use &Text. If you want to use an ampersand character in the string, use the static style SS_NOPREFIX.


See Also

Modifying Static Controls

Querying Static Controls


Modifying Static Controls (ObjectWindows)

See Also

TStatic has two member functions for altering the text of a static control: SetText sets the text to the passed string, and Clear erases the text. You cannot change the text of static controls created with the SS_SIMPLE style.


See Also

Constructing Static Control Objects

Querying Static Controls


Querying Static Controls (ObjectWindows)

See Also

TStatic::GetTextLen returns the length of the static control's text. To get the text itself, use TStatic::GetText.


See Also

Constructing Static Control Objects

Modifying Static Controls

TStatic


Constructing Buttons (ObjectWindows)

See Also

Buttons (sometimes called pushbuttons or command buttons) perform a task each time the button is pressed. There are two kinds of buttons: default buttons and non-default buttons. A default button, distinguished by the button style BS_DEFPUSHBUTTON, has a bold border that indicates the default user response. Non-default buttons have the button style BS_PUSHBUTTON.

See EXAMPLES\OWL\OWLAPI\BWCC for an example of button controls.

One of TButton's constructors takes the seven parameters commonly found in a control object constructor (a parent window, a resource identifier, the control's x, y, h, and w dimensions, and an optional module pointer), plus a text string that specifies the button's label, and a bool flag that indicates whether the button should be a default button. Here is the constructor declaration:

TButton(TWindow *parent, int resourceId, const char far *text, int X, int Y, int W, int H, bool isDefault = false, TModule *module = 0);

A typical button would be constructed like this:

btn = new TButton(this, ID_BUTTON, "DO_IT!", 38, 48, 316, 24, true);


See Also

Responding To Buttons

TButton


Responding To Buttons (ObjectWindows)

See Also

When the user clicks a button, the button's parent window receives a notification message. If the parent window object intercepts the message, it can respond to these events by displaying a dialog box, saving a file, and so on.

To intercept and respond to button messages, define a command response member function for the button. The following example uses ID ID_BUTTON to handle the response to the user clicking the button:

DEFINE_RESPONSE_TABLE1(TTestWindow, TFrameWindow)

  EV_COMMAND(ID_BUTTON, HandleButtonMsg),

END_RESPONSE_TABLE;

void TTestWindow::HandleButtonMsg()

{

  // Button was pressed

}


See Also

Constructing Buttons

TButton


Using Check Box and Radio Button Controls (ObjectWindows)

See Also

A check box generally presents the user with a two-state option. The user can check or uncheck the control, or leave it as is. In a group of check boxes, any or all might be checked. For example, you might use a check box to enable or disable the use of sound in your application.

Radio buttons, on the other hand, are used for selecting one of several mutually exclusive options. For example, you might use radio buttons to choose between a number of sounds in your application.

TCheckBox is derived from TButton and represents check boxes. Since radio buttons share some behavior with check boxes, TRadioButton is derived from TCheckBox.

Check boxes and radio buttons are sometimes collectively referred to as selection boxes. While displayed on the screen, a selection box is either checked or unchecked. When the user clicks a selection box, it is an event, generating a Windows notification. As with other controls, the selection box's parent window usually intercepts and acts on these notifications.

See EXAMPLES\OWL\OWLAPI\BUTTON for radio button and check box control examples.


See Also

Constructing Check Boxes and Radio Buttons


Constructing Check Boxes and Radio Buttons (ObjectWindows)

See Also

TCheckBox and TRadioButton each has a constructor that takes the seven parameters commonly found in a control object constructor (a parent window, a resource identifier, the control's x, y, h, and w dimensions, and an optional module pointer). They also take a text string and a pointer to a group box object that groups the selection boxes. If the group box object pointer is zero, the selection box is not part of a group box. Here are one each of their constructors:

TCheckBox(TWindow *parent,

          int resourceId,

          const char far *title,

          int x, int y, int w, int h,

          TGroupBox *group = 0,

          TModule *module = 0);

TRadioButton(TWindow *parent,

             int resourceId,

             const char far *title,

             int x, int y, int w, int h,

             TGroupBox *group = 0,

             TModule *module = 0);

The following listing shows some typical constructor calls for selection boxes.

CheckBox = new TCheckBox(this, ID_CHECKBOX, "Check Box Text", 158, 12, 	150, 26);

GroupBox = new TGroupBox(this, ID_GROUPBOX, "Group Box", 158, 102, 	176, 108);

RButton1 = new TRadioButton(this, ID_RBUTTON1, "Radio Button 1", 174, 	128, 138, 24, GroupBox);

RButton2 = new TRadioButton(this, ID_RBUTTON2, "Radio Button 2", 174, 	162, 138, 24, GroupBox);

Check boxes by default have the BS_AUTOCHECKBOX style, which means that Windows handles a click on the check box by toggling the check box. Without BS_AUTOCHECKBOX, you would have to set the check box's state manually. Radio buttons by default have the BS_AUTORADIOBUTTON style, which means that Windows handles a click on the radio button by checking the radio button and unchecking the other radio buttons in the group. Without BS_AUTORADIOBUTTON, you would  have to intercept the radio button's notification messages and do this work yourself.


See Also

Using Check Box and Radio Button Controls


Modifying Selection Boxes (ObjectWindows)

See Also

Checking and unchecking a selection box seems like a job for the application user, not your application. But in some cases, your application needs control over a selection box's state. For example, if the user opens a text file, you might want to automatically check a check box labeled "Save as ANSI text." TCheckBox defines several member functions for modifying a check box's state:

TCheckBox member functions for modifying selection boxes

Member function	Description

Check or SetCheck(BF_CHECKED)	Check

Uncheck or SetCheck(BF_UNCHECKED)	Uncheck

Toggle	Toggle

SetState	Highlight

SetStyle	Change the button's style

When you use these member functions with radio buttons, ObjectWindows ensures that only one radio button per group is checked, as long as the buttons are assigned to a group.


See Also

Querying Selection Boxes


Querying Selection Boxes (ObjectWindows)

See Also

Querying a selection box is one way to find out and respond to its state. Radio buttons have two states: checked (BF_CHECKED) and unchecked (BF_UNCHECKED). Check boxes can have an additional (and optional) third state: grayed (BF_GRAYED). The following table summarizes the selection-box query member functions.

TCheckBox member functions for querying selection boxes

Member function	Description

GetCheck	Return the check state.

GetState	Return the check, highlight, or focus state.


See Also

Modifying Selection Boxes

TCheckBox


Constructing Group Boxes (ObjectWindows)

See Also

In its simplest form, a group box is a labeled static rectangle that visually groups other controls.

TGroupBox has a constructor that takes the seven parameters commonly found in a control object constructor (a parent window, a resource identifier, the control's x, y, h, and w dimensions, and an optional module pointer), and also takes a text string parameter to label the group:

TGroupBox(TWindow *parent, int resourceId, const char far *text, int X, int Y, int W, int H, TModule *module = 0);


See Also

Grouping Controls

Responding To Group Boxes


Grouping Controls (ObjectWindows)

See Also

Usually a group box visually associates a group of other controls; however, it can also logically associate a group of selection boxes (check boxes and radio buttons). This logical group performs automatic unchecking (BS_AUTOCHECKBOX, BS_AUTORADIOBUTTON).

To add a selection box to a group box, pass a pointer to the group box object in the selection box's constructor call.


See Also

Constructing Group Boxes

Responding To Group Boxes

TGroupBox


Responding To Group Boxes (ObjectWindows)

See Also

When an event occurs that might change the group box's selections (for example, when a user clicks a button or the application calls Check), Windows sends a notification message to the group box's parent window. The parent window can intercept the message for the group box as a whole, rather than responding to the individual selection boxes in the group box. To find out which control in the group was affected, you can read the current status of each control.


See Also

Constructing Group Boxes

Grouping Controls

TGroupBox


Using Scroll Bars (ObjectWindows)

See Also

Scroll bars are the primary mechanism for changing the user's view of an application window, a list box, or a combo box. However, you might want a separate scroll bar to perform a specialized task, such as controlling the temperature on a thermostat or the color in a drawing program. Use TScrollBar objects when you need a separate, customizable scroll bar.

See EXAMPLES\OWL\OWLAPI\SCROLLER for a scroll bar control example.


See Also

Constructing Scroll Bars

Controlling the Scroll Bar Range

Controlling Scroll Amounts

Querying Scroll Bars

Modifying Scroll Bars

Responding To Scroll-bar Messages


Constructing Scroll Bars (ObjectWindows)

See Also

TScrollBar has a constructor that takes the seven parameters commonly found in a control object constructor (a parent window, a resource identifier, the control's x, y, h, and w dimensions, and an optional module pointer), and also takes a bool flag parameter that specifies whether the scroll bar is horizontal. Here's a TScrollBar constructor declaration:

TScrollBar(TWindow *parent, int resourceId, int x, int y, int w, int h, bool isHScrollBar, TModule *module = 0);

If you specify a height of zero for a horizontal scroll bar or a width of zero for a vertical scroll bar, Windows gives it a standard height and width. The following code creates a standard-height horizontal scroll bar:

new TScrollBar(this, ID_THERMOMETER, 100, 150, 180, 0, true);

TScrollBar's constructor constructs scroll bars with the style SBS_HORZ for horizontal scroll bars and SBS_VERT for vertical scroll bars. You can specify additional styles, such as SBS_TOPALIGN, by changing the scroll bar object's Attr.Style.


See Also

Using Scroll Bars

Controlling the Scroll Bar Range

Controlling Scroll Amounts

Querying Scroll Bars

Modifying Scroll Bars

Responding To Scroll-bar Messages


Controlling the Scroll Bar Range (ObjectWindows)

See Also

One attribute of a scroll bar is its range, which is the set of all possible thumb positions. The thumb is the scroll bar's sliding box that the user drags or scrolls. Each position is associated with an integer. The parent window uses this integer, the position, to set and query the scroll bar. By default, a scroll bar object's range is 1 to 100.

The thumb's minimum position (at the top of a vertical scroll bar and the left of a horizontal scroll bar) corresponds to position 1, and the thumb's maximum position corresponds to position 100. Use SetRange to set the range differently.


See Also

Using Scroll Bars

Constructing Scroll Bars

Controlling Scroll Amounts

Querying Scroll Bars

Modifying Scroll Bars

Responding To Scroll-bar Messages


Controlling Scroll Amounts (ObjectWindows)

See Also

A scroll bar has two other important attributes: its line magnitude and page magnitude. The line magnitude, initialized to 1, is the distance, in range units, the thumb moves when the user clicks the scroll bar's arrows. The page magnitude, initialized to 10, is the distance, also in range units, the thumb moves when the user clicks the scrolling area. You can change these values by changing the TScrollBar data members LineMagnitude and PageMagnitude.


See Also

Using Scroll Bars

Constructing Scroll Bars

Controlling the Scroll Bar Range

Querying Scroll Bars

Modifying Scroll Bars

Responding To Scroll-bar Messages


Querying Scroll Bars (ObjectWindows)

TScrollBar has two member functions for querying scroll bars:

GetRange gets the upper and lower ranges.

GetPosition gets the current thumb position.

See Also

Using Scroll Bars

Constructing Scroll Bars

Controlling the Scroll Bar Range

Controlling Scroll Amounts

Modifying Scroll Bars

Responding To Scroll-bar Messages


Modifying Scroll Bars (ObjectWindows)

See Also

Modifying scroll bars is usually done by the user, but your application can also modify a scroll bar directly:

SetRange sets the scrolling range.

SetPosition sets the thumb position.

DeltaPos moves the thumb position.


See Also

Using Scroll Bars

Constructing Scroll Bars

Controlling the Scroll Bar Range

Controlling Scroll Amounts

Querying Scroll Bars

Responding To Scroll-bar Messages


Responding To Scroll-bar Messages (ObjectWindows)

See Also

When the user moves a scroll bar's thumb or clicks the scroll arrows, Windows sends a scroll bar notification message to the parent window. If you want your window to respond to scrolling events, respond to the notification messages.

Scroll bar notification messages are slightly different from other control notification messages. They're based on the WM_HSCROLL and WM_VSCROLL messages, rather than WM_COMMAND command messages. Therefore, to respond to scroll bar notification messages, you need to define EvHScroll or EvVScroll event response functions, depending on whether the scroll bar is horizontal or vertical, as shown in the following example:

class TTestWindow : public TFrameWindow {

  public:

    TTestWindow(TWindow* parent, const char* title);

    virtual void SetupWindow();

    void EvHScroll(UINT code, UINT pos, HWND wnd);

  DECLARE_RESPONSE_TABLE(TTestWindow);

};

DEFINE_RESPONSE_TABLE1(TTestWindow, TFrameWindow)

  EV_WM_HSCROLL,

END_RESPONSE_TABLE;

Usually, you respond to all the scroll bar notification messages by retrieving the current thumb position and taking appropriate action. In that case, you can ignore the notification code, as shown in the following example:

void TTestWindow::EvHScroll(UINT code, UINT pos, HWND wnd)

{

  TFrameWindow::EvHScroll(); // perform default WM_HSCROLL processing

  int newPos = ScrollBar->GetPosition();

  // do some processing with newPos

}


See Also

Using Scroll Bars

Constructing Scroll Bars

Controlling the Scroll Bar Range

Controlling Scroll Amounts

Querying Scroll Bars

Modifying Scroll Bars


Avoiding Thumb Tracking Messages (ObjectWindows)

See Also

You might not want to respond to the scroll bar notification messages while the user is dragging the scroll bar's thumb, because the user is usually dragging the thumb quickly, generating many notification messages. It is more efficient to wait until the user has stopped moving the thumb and then respond. To do this, screen out the notification messages that have the SB_THUMBTRACK code.


See Also

Using Scroll Bars

Specializing Scroll Bar Behavior

Using Sliders and Gauges


Specializing Scroll Bar Behavior (ObjectWindows)

See Also

You might want a scroll bar object respond to its own notification messages. TWindow has built-in support for dispatching scroll bar notification messages back to the scroll bar. TWindow::EvHScroll or TWindow::EvVScroll executes the appropriate TScrollBar member function based on the notification code. For example:

class TSpecializedScrollBar : public TScrollBar {

public:

   virtual void SBTop();

   };

void TSpecializedScrollBar::SBTop() {

   TScrollBar::SBTop();

   ::sndPlaySound("AT-TOP.WAV", SND_ASYNC); // play sound

   }

Be sure to call the base member functions first. They correctly update the scroll bar to its new position.

The following table associates notification messages with the corresponding TScrollBar member function:

Notification message	TScrollBar member function

SB_LINEUP	SBLineUp

SB_LINEDOWN	SBLineDown

SB_PAGEUP	SBPageUp

SB_PAGEDOWN	SBPageDown

SB_THUMBPOSITION	SBThumbPosition

SB_THUMBTRACK	SBThumbTrack

SB_TOP	SBTop

SB_BOTTOM	SBBottom


See Also

Using Scroll Bars

Avoiding Thumb Tracking Messages

Using Sliders and Gauges

TScrollBar::EvHScroll

TScrollBar::EvVScroll


Using Sliders and Gauges (ObjectWindows)

See Also

Sliders are specialized scrollers used for nonscrolling position information. The abstract base class TSlider is derived from the TScrollBar class. Like other control constructors, the TSlider constructor takes the seven parameters commonly found in a control object constructor (a parent window, a resource identifier, the control's x, y, h, and w dimensions, and an optional module pointer), and also takes a TResId object, which is a bitmap resource identifier. The bitmap is displayed as the thumb knob for the slider. Heres the TSlider constructor:

THSlider(TWindow* parent,

         int id,

         int X, int Y, int W, int H,

         TResId thumbResId = IDB_HSLIDERTHUMB,

         TModule* module = 0);

To implement a class based on TSlider, you must implement a number of functions which are declared as pure virtual functions in TSlider:

Pure virtual functions in TSlider

Name	Function

HitTest	Determines whether a point in inside the thumb or any other hot area of the slider.

NotifyParent	Notifies the sliders parent of a scroll event.

PaintRuler	Paints the ruler.

PaintSlot	Paints the slot that the thumb rides over.

PointToPos	Converts a point inside the slider to a slider position.

PosToPoint	Converts a slider position to a point inside the slider.

SetupThumbRgn	Sets up the thumb region. By default, this is a simple rectangle.

SlideThumb	Slides the thumb and does the required blitting and painting.

Two classes derived from TSlider, THSlider and TVSlider, implement vertical and horizontal slider versions. Both THSlider and TVSlider have only one constructor. These constructors resemble the TSlider constructor, with the exception that each has a default value for the thumb knob bitmap:

THSlider(TWindow* parent,

         int id,

         int X, int Y, int W, int H,

         TResId thumbResId = IDB_HSLIDERTHUMB,

         TModule* module = 0);

TVSlider(TWindow* parent,

         int id,

         int X, int Y, int W, int H,

         TResId thumbResId = IDB_VSLIDERTHUMB,

         TModule* module = 0);

Gauges are controls that display duration or other information about an ongoing process. Class TGauge implements gauges, and is derived from class TControl. The TGauge constructor looks like this:

TGauge(TWindow* parent,

       const char far* title,

       int id,

       int X, int Y, int W, int H,

       bool isHorizontal = true,

       int margin = 0,

       TModule *module = 0);

The TGauge constructor has the normal control constructor parameters (a parent window, a resource identifier, the control's x, y, h, and w dimensions, and an optional module pointer).

The isHorizontal parameter determines whether you get a horizontal or vertical gauge. If isHorizontal is true, the gauge is displayed horizontally. If isHorizontal is false, the gauge is displayed vertically. The default is horizontal. Horizontal gauges are usually used to display process information, and vertical gauges are usually used to display analog information.

The margin parameter determines the size of the gauge's margin.

See EXAMPLES\OWL\OWLAPI\SLIDER for slider and gauge control examples.


See Also

Using Scroll Bars


Using Edit Controls (ObjectWindows)

See Also

Edit controls are interactive static controls. They are rectangular areas that can be filled with text, modified, and cleared by the user or application. Edit controls are very useful as fields for data entry screens. They support the following operations:

User text input

Dynamic display of text (by the application)

Cutting, copying, and pasting to the Clipboard

Multiline editing (good for text editors)

See EXAMPLES\OWL\OWLAPI\VALIDATE for an edit controls example.


See Also

Constructing Edit Controls

Using the Clipboard and the Edit Menu

Querying Edit Controls

Modifying Edit Controls


Constructing Edit Controls (ObjectWindows)

See Also

One of TEdit's constructors takes parameters for an initial text string, maximum string length (including the terminating NULL), and a bool flag specifying whether or not it Is a multiline edit control (in addition to the parent window, resource identifier, and placement coordinates). This TEdit constructor is declared as follows:

TEdit(TWindow *parent, int resourceId, const char far *text, int x, int y, int w, int h, UINT textLen = 0, bool multiline = false, TModule *module = 0);

By default, the edit control has the styles ES_LEFT (for left-aligned text), ES_AUTOHSCROLL (for automatic horizontal scrolling), and WS_BORDER (for a visible border surrounding the edit control). Multiline edit controls get the additional styles ES_MULTILINE (specifies a multiline edit control), ES_AUTOVSCROLL (automatic vertical scrolling), WS_VSCROLL (vertical scroll bar), and WS_HSCROLL (horizontal scroll bar).

The following are typical edit control constructor calls, one for a single-line control, the other multiline:

Edit1 = new TEdit(this, ID_EDIT1, "Default Text", 20, 50, 150, 30, 	MAX_TEXTLEN, false);

Edit2 = new TEdit(this, ID_EDIT2, "", 260, 50, 150, 30, MAX_TEXTLEN, 	true);


See Also

Using Edit Controls

Using the Clipboard and the Edit Menu

Querying Edit Controls

Modifying Edit Controls


Using the Clipboard and the Edit Menu (ObjectWindows)

See Also

You can directly transfer text between an edit control object and the Windows Clipboard using TEdit member functions. You probably want to give users access to these member functions by giving your window an Edit menu.

Edit control objects have built-in responses to menu items like Edit|Copy and Edit|Undo. TEdit has command response member functions, such as CmEditCopy and CmEditUndo, which ObjectWindows invokes in response to users choosing items from the parent window's Edit menu.

The following table shows the Clipboard and editing member functions and the menu commands that invoke them:

TEdit member functions and Edit menu commands

Member function	Menu command	Description

Copy	CM_EDITCOPY	Copy text to Clipboard.

Cut	CM_EDITCUT	Cut text to Clipboard.

Undo	CM_EDITUNDO	Undo last edit.

Paste	CM_EDITPASTE	Paste text from Clipboard.

DeleteSelection	CM_EDITDELETE	Delete selected text.

Clear	CM_EDITCLEAR	Clear entire edit control.

To add an editing menu to a window that contains edit control objects, define a menu resource for the window using the menu commands listed above. You do not need to write any new member functions.


See Also

Using Edit Controls

Constructing Edit Controls

Querying Edit Controls

Modifying Edit Controls


Querying Edit Controls (ObjectWindows)

See Also

Often, you want to query an edit control to store the entry for later use. TEdit has a number of querying member functions. Many of the edit control query and modification member functions return, or require you to specify, a line number or a character's position in a line. All of these indexes start at zero. In other words, the first line is line zero and the first character of a line is character zero.

The following table summarizes TEdit's query member functions.

Member function	Description

IsModified	Find out if text has changed.

GetText	Retrieve all text.

GetLine	Retrieve a line.

GetNumLines	Get number of lines.

GetLineLength	Get length of a given line.

GetSelection	Get index of selected text.

GetSubText	Get a range of characters.

GetLineIndex	Count characters before a line.

GetLineFromPos	Find the line containing an index.

GetRect	Get formatting rectangle.

GetHandle	Get memory handle.

GetFirstVisibleLine	Get index of first visible line.

GetPasswordChar	Get character used in passwords.

GetWordBreakProc	Get word-breaking procedure.

CanUndo	Find out if edit can be undone.

Text that spans lines in a multiline edit control contains two extra characters for each line break: a carriage return ('\r') and a line feed ('\n'). TEdit's member functions retain the text's formatting when they return text from a multiline edit control. When you insert this text back into an edit control, paste it from the Clipboard, write it to a file, or print it to a printer, the line breaks appear as they did in the edit control. When you use query member functions to get a specified number of characters, be sure to account for the two extra characters in a line break.


See Also

Using Edit Controls

Constructing Edit Controls

Using the Clipboard and the Edit Menu

Modifying Edit Controls


Modifying Edit Controls (ObjectWindows)

See Also

Many uses of edit controls require that your application explicitly substitute, insert, clear, or select text. TEdit supports those operations, plus the ability to force the edit control to scroll.

TEdit member functions for modifying edit controls

Member function	Description

Clear	Delete all text.

DeleteSelection	Delete selected text.

DeleteSubText	Delete a range of characters.

DeleteLine	Delete a line of text.

Insert	Insert text.

Paste	Paste text from Clipboard.

SetText	Replace all text.

SetSelection	Select a range of text.

Scroll	Scroll text.

ClearModify	Clear the modified flag.

Search	Search for text.

SetRect or SetRectNP	Set formatting rectangle.

FormatLines	Turn on or off soft line breaks.

SetTabStops	Set tab stops.

SetHandle	Set local memory handle.

SetPasswordChar	Set password character.

SetReadOnly	Make the edit control read-only.

SetWordBreakProc	Set word-breaking procedure.

EmptyUndoBuffer	Empty undo buffer.


See Also

Using Edit Controls

Constructing Edit Controls

Using the Clipboard and the Edit Menu

Querying Edit Controls


Using Combo Boxes (ObjectWindows)

See Also

A combo box control is a combination of two other controls: a list box and an editor static control. It serves the same purpose as a list box -- it lets the user choose one text item from a scrollable list of text items by clicking the item with the mouse. The edit control, grafted to the top of the list box, provides another selection mechanism, allowing users to type the text of the desired item. If the list box area of the combo box is displayed, the desired item is automatically selected. TComboBox is derived from TListBox and inherits its member functions for modifying, querying, and selecting list items. In addition, TComboBox provides member functions for manipulating the list part of the combo box, which, in some types of combo boxes, can drop down on request.

See EXAMPLES\OWL\OWLAPPS\OWLCMD for a combo box control example.


See Also

Varieties Of Combo Boxes

Choosing Combo Box Types

Constructing Combo Boxes

Modifying Combo Boxes

Querying Combo Boxes


Varieties Of Combo Boxes (ObjectWindows)

See Also

There are three types of combo boxes: simple, drop down, and drop down list. All combo boxes show their edit area at all times, but some can show and hide their list box areas. The following table summarizes the properties of each type of combo box.

Style	Can hide list?	Text must match list?

Simple	No	No

Drop down	Yes	No

Drop down list	Yes	Yes

From a user's perspective, these are the distinctions between the different styles of combo boxes:

A simple combo box cannot hide its list box area. Its edit area behaves just like an edit control; the user can enter and edit text, and the text does not need to match one of the items in the list. If the text does match, the corresponding list item is selected.

A drop down combo box behaves like a simple combo box, with one exception. In its initial state, its list area is not displayed. It appears when the user clicks on the icon to the right of the edit area. When drop down combo boxes are not being used, they take up less space than a simple combo box or a list box.

The list area of a drop down list combo box behaves like the list area of a drop down combo box--it appears only when needed. The two combo box types differ in the behavior of their edit areas. Whereas drop down edit areas behave like regular edit controls, drop down list edit areas are limited to displaying only the text from one of their list items. When the edit text matches the item text, no more characters can be entered.


See Also

Using Combo Boxes

Choosing Combo Box Types

Constructing Combo Boxes

Modifying Combo Boxes

Querying Combo Boxes


Choosing Combo Box Types (ObjectWindows)

See Also

Drop down list combo boxes are useful in cases where no other selection is acceptable besides those listed in the list area. For example, when choosing a printer, you can only choose a printer accessible from your system.

On the other hand, drop down combo boxes can accept entries other than those found in the list. A typical use of drop down combo boxes is selecting disk files for opening or saving. The user can either search through directories to find the appropriate file in the list, or type the full path name and file name in the edit area, regardless of whether the file name appears in the list area.


See Also

Using Combo Boxes

Varieties Of Combo Boxes

Constructing Combo Boxes

Modifying Combo Boxes

Querying Combo Boxes


Constructing Combo Boxes (ObjectWindows)

See Also

TComboBox has two constructors. The first takes the seven parameters commonly found in a control object constructor (a parent window, a resource identifier, the control's x, y, h, and w dimensions, and an optional module pointer), and also style and maximum text length parameters. This constructor is declared like this:

TComboBox(TWindow *parent, int id, int x, int y, int w, int h, uint32 style, uint16 textLen, TModule *module = 0);

All combo boxes have the styles WS_CHILD, WS_VISIBLE, WS_GROUP, WS_TABSTOP, CBS_SORT (to sort the list items), CBS_AUTOHSCROLL (to let the user enter more text than fits in the visible edit area), and  WS_VSCROLL (vertical scroll bar). The style parameter you supply is one of the Windows combo box styles CBS_SIMPLE, CBS_DROPDOWN, or CBS_DROPDOWNLIST. The text length specifies the maximum number of characters allowed in the edit area.

The second TComboBox constructor lets you create an ObjectWindows object that serves as an alias for an existing combo box. This constructor looks like this:

TComboBox(TWindow* parent,

          int resourceId,

          UINT textLen = 0,

          TModule* module = 0);

The following lines show a typical combo box constructor call, constructing a drop down list combo box with an unsorted list:

Combo1 = new TComboBox(this, ID_COMBO1, 190, 30, 150, 100,
                       CBS_SIMPLE, 20);

Combo1->Attr.Style &= ~CBS_SORT;


See Also

Using Combo Boxes

Varieties Of Combo Boxes

Choosing Combo Box Types

Modifying Combo Boxes

Querying Combo Boxes


Modifying Combo Boxes (ObjectWindows)

See Also

TComboBox defines several member functions for modifying a combo box's list and edit areas. Because TComboBox is derived from TListBox, you can also use TListBox member functions to manipulate a combo box's list area.

The following table summarizes these TComboBox member functions:

Member function	Description

SetText	Replace all text in the edit area.

SetEditSel	Select text in the edit area.

Clear	Delete all text in the edit area.

ShowList or ShowList(true)	Show the list area.

HideList or ShowList(false)	Hide the list area.

SetExtendedUI	Set the extended combo box UI.


See Also

Using Combo Boxes

Varieties Of Combo Boxes

Choosing Combo Box Types

Constructing Combo Boxes

Querying Combo Boxes


Querying Combo Boxes (ObjectWindows)

See Also

TComboBox adds several member functions to those inherited from TListBox for querying the contents of a combo box's edit and list areas. The following table summarizes these member functions.

Member function	Description

GetTextLen	Get length of text in edit area.

GetText	Retrieve all text in edit area.

GetEditSel	Get indexes of selected text in edit area.

GetDroppedControlRect	Get rectangle of dropped-down list.

GetDroppedState	Determine if list area is visible.

GetExtendedUI	Determine if combo box has extended UI.


See Also

Using Combo Boxes

Varieties Of Combo Boxes

Choosing Combo Box Types

Constructing Combo Boxes

Modifying Combo Boxes


Setting and Reading Control Values (ObjectWindows)

To manage complex dialog boxes or windows with many child-window controls, you might create a derived class to store and retrieve the state of the dialog box or window controls. The state of a control includes the text of an edit control, the position of a scroll bar, and whether a radio button is checked.

As an alternative to creating a derived class, you can use a structure to represent the state of the dialog box's or window's controls. This structure is called a transfer buffer and is described in Using Transfer Buffers.


Using Transfer Buffers (ObjectWindows)

See Also

As an alternative to creating a derived class to manage complex dialog boxes or windows with many child-window controls, you can use a structure to represent the state of the dialog box's or the window's controls. This structure is called a transfer buffer because control states are transferred to the buffer from the controls and to the controls from the buffer.

For example, your application can bring up a modal dialog box and, after the user closes it, extract information from the transfer buffer about the state of each control. Then, if the user brings up the dialog box again, you can transfer the control states from the transfer buffer. In addition, you can set the initial state of each control based on the transfer buffer. You can also explicitly transfer data in either direction at any time, such as to reset the states of the controls to their previous values. A window or modeless dialog box with controls can also use the transfer mechanism to set or retrieve state information at any time.

The transfer mechanism requires the use of ObjectWindows objects to represent the controls for which you'd like to transfer data. To use the transfer mechanism, you have to do three things:

Define the transfer buffer, with an instance variable for each control for which you want to transfer data.

Define the corresponding window or dialog box.

Transfer the data.


See Also

Associating Interface Objects with Controls

Setting and Reading Control Values


Defining the Transfer Buffer (ObjectWindows)

See Also

The transfer buffer is a structure with one member for each control participating in the transfer. These members are known as instance variables. A window or dialog box can also have controls with no states to transfer. For example, by default, buttons, group boxes, and static controls do not participate in transfer. The type of the control determines the type of member needed in the transfer buffer.

To define a transfer buffer, define an instance variable for each participating control in the dialog box or window. It is not necessary to define an instance variable for every control, only for those controls you want to transfer values to and from. The transfer buffer stores one of each type of control, except buttons, group boxes, and static controls. For example:

struct TSampleTransferStruct

{

  char editCtl[sizeOfEditCtl]; // edit control

  uint16 checkBox;             // check box

  uint16 radioButton;          // radio button

  TListBoxData listBox;        // list box

  TComboBoxData comboBox;      // combo box

  TScrollBarData scrollBar;    // scroll bar

};

Each type of control has different information to store. The following table explains the transfer buffer for each of ObjectWindows' controls.

Transfer buffer members for each type of control

Control type	Type	Description

Static	char array	A character array up to the maximum length of text allowed, plus the terminating NULL. By default, static controls do not participate in transfer, but you can explicitly enable them.

Edit	char array	A character array up to the maximum length of text allowed, plus the terminating NULL.

List box	TListBoxData	An instance of the TListBoxData class; TListBoxData has several members for holding the list box strings, item data, and the selected indexes.

Combo box	TComboBoxData	An instance of the TComboBoxData class; TComboBoxData has several members for holding the combo box list area strings, item data, the selection index, and the contents of the edit area.

Check box or	uint16	BF_CHECKED, BF_UNCHECKED, or

radio button	BF_GRAYED, indicating selection box state.

Scroll bar	TScrollBarData	An instance of TScrollBarData, which has three int members:
LowValue -- minimum range
HighValue -- maximum range
Position -- current thumb position.


See Also

Using Transfer Buffers


List Box Transfer (ObjectWindows)

See Also

Because list boxes need to transfer several pieces of information (strings, item data, and selection indexes), the transfer buffer uses a class called TListBoxData. TListBoxData has several data members to hold the list box information:

TListBoxData data members

Data member	Type	Description

ItemDatas	TUint32Array*	Contains the item data uint32 for each item in the list box.

SelIndices	TIntArray*	Contains the indexes of each selected string (in a multiple-selection list box).

Strings	TStringArray*	Contains all the strings in the list box.

TListBoxData also has the following member functions to manipulate the list box data:

Member function	Description

AddItemData	Adds item data to the ItemDatas array.

AddString	Adds a string to the Strings array, and optionally selects it.

AddStringItem	Adds a string to the Strings array, optionally selects it, and adds item data to the ItemDatas array.

GetSelString	Get the selected string at the given index.

GetSelStringLength	Returns the length of the selected string at the given index.

ResetSelections	Removes all selections from the SelIndices array.

Select	Selects the string at the given index.

SelectString	Selects the given string.


See Also

Combo Box Transfer

Defining the Corresponding Window Or Dialog Box

Using Transfer with a Dialog Box

Transferring the Data

Transferring Data From a Dialog Box

Supporting Transfer For Customized Controls


Combo Box Transfer (ObjectWindows)

See Also

Combo boxes need to transfer several pieces of information (strings, item data, selected item, and the index of the selected item). The transfer buffer for combo boxes is a class called TComboBoxData. TComboBoxData has the following data members to hold the combo box information:

Data member	Type	Description

ItemDatas	TUint32Array*	Contains the item data uint32 for each item in the list box.

Selection	char*	Contains the selected string.

Strings	TStringArray*	Contains all the strings in the list box.

TComboBoxData also uses the following member functions to manipulate the combo box information:

Member function	Description

AddString	Adds a string to the Strings array, and optionally selects it.

AddStringItem	Adds a string to the Strings array, optionally selects it, and adds item data to the ItemDatas array.

Clear	Clears all data.

GetItemDatas	Returns a reference to ItemDatas.

GetSelCount	Returns the number of selected items.

GetSelection	Returns a reference to the current selection.

GetSelIndex	Returns the index of the current selection.

GetSelString	Places a copy of the current selection into a character buffer.

GetSelStringLength	Returns the length of the currently selected string.

GetStrings	Returns a reference to the entire array of strings in the combo box.

ResetSelections	Sets the current selection to a null string and sets the index to CB_ERR.

Select	Sets a string in Strings to be the current selection, based on an index parameter.

SelectString	Sets a string in Strings to be the current selection, based on matching a const char far* parameter.


See Also

List Box Transfer

Defining the Corresponding Window Or Dialog Box

Using Transfer with a Dialog Box

Transferring the Data

Transferring Data From a Dialog Box

Supporting Transfer For Customized Controls


Defining the Corresponding Window Or Dialog Box (ObjectWindows)

See Also

A window or dialog box that uses the transfer mechanism must construct its participating control objects in the exact order in which the corresponding transfer buffer members are defined. To enable transfer for a window or dialog box object, call SetTransferBuffer and pass a pointer to the transfer buffer.


See Also

Using Transfer with a Dialog Box

Using Transfer with a Window

Transferring the Data

Using Transfer Buffers

List Box Transfer

Combo Box Transfer

Transferring Data To a Window

Transferring Data From a Dialog Box

Transferring Data From a Window

Supporting Transfer For Customized Controls


Using Transfer with a Dialog Box (ObjectWindows)

See Also

Because dialog boxes get their definitions and the definitions of their controls from resources, you should construct control objects using the constructors that take resource IDs. For example:

struct TTransferBuffer {

  char edit[30];

  TListBoxData listBox;

  TScrollBarData scrollBar;

}

   .

   .

   .

TTransferDialog::TTransferDialog(TWindow* parent, int resId)

  : TDialog(parent, resId),

    TWindow(parent)

{

  new TEdit(this, ID_EDIT, 30);

  new TListBox(this, ID_LISTBOX);

  new TScrollBar(this, ID_SCROLLBAR);

  SetTransferBuffer(&TTransferBuffer);

}

Control objects you construct like this automatically have transfer enabled (except for button, group box, and static control objects). To explicitly exclude a control from the transfer mechanism, call its DisableTransfer member function after constructing it.


See Also

List Box Transfer

Combo Box Transfer

Defining the Corresponding Window Or Dialog Box

Transferring the Data

Transferring Data From a Dialog Box

Supporting Transfer For Customized Controls


Using Transfer with a Window (ObjectWindows)

See Also

Controls constructed in a window have transfer disabled by default. To enable transfer, call the control object's EnableTransfer member function:

ListBox = new TListBox(this, ID_LISTBOX, 20, 20, 340, 100);

ListBox->EnableTransfer();


See Also

Defining the Corresponding Window Or Dialog Box

Using Transfer with a Window

Transferring the Data

Transferring Data To a Window

Transferring Data From a Window

Supporting Transfer For Customized Controls


Transferring the Data (ObjectWindows)

See Also

In most cases, transferring data to or from a window is automatic, but you can also explicitly transfer data at any time.


See Also

Transferring Data To a Window

Transferring Data From a Dialog Box

Transferring Data From a Window

Supporting Transfer For Customized Controls

Defining the Corresponding Window Or Dialog Box

Using Transfer Buffers

Combo Box Transfer

List Box Transfer

Using Transfer with a Dialog Box

Using Transfer with a Window


Transferring Data To a Window (ObjectWindows)

See Also

Transfer to a window happens automatically when you construct a window object. The constructor calls SetupWindow to create an interface element to represent the window object; it then calls TransferData to load any data from the transfer buffer. The window object's SetupWindow calls SetupWindow for each of its child windows as well, so each of the child windows has a chance to transfer its data. Because the parent window sets up its child windows in the order it constructed them, the data in the transfer buffer must appear in that same order.


See Also

Transferring Data From a Dialog Box

Transferring Data From a Window

Supporting Transfer For Customized Controls

Transferring the Data

Defining the Corresponding Window Or Dialog Box

Combo Box Transfer

List Box Transfer

Using Transfer with a Dialog Box

Using Transfer with a Window


Transferring Data From a Dialog Box (ObjectWindows)

See Also

When a modal dialog box receives a command message with a control ID of IDOK, it automatically transfers data from the controls into the transfer buffer. Usually this message indicates that the user chose OK to close the dialog box, so the dialog box automatically updates its transfer buffer. Then, if you execute the dialog box again, it transfers from the transfer buffer to the controls.


See Also

Transferring Data From a Window

Transferring Data to a Window

Supporting Transfer For Customized Controls

Transferring the Data

Defining the Corresponding Window Or Dialog Box

Combo Box Transfer

List Box Transfer

Defining the Corresponding Window Or Dialog Box

Using Transfer with a Dialog Box


Transferring Data From a Window (ObjectWindows)

See Also

You can explicitly transfer data in either direction at any time. For example, you might want to transfer data out of controls in a window or modeless dialog box. Or you might want to reset the state of the controls using the data in the transfer buffer in response to the user clicking a Reset or Revert button.

Use the TransferData member function in either case, passing the tdSetData enumeration to transfer from the transfer buffer to the controls or tdGetData to transfer from the controls to the transfer buffer. For example, you might want to call TransferData in the CloseWindow member function of a window object as follows:

void TMyWindow::CloseWindow()

{

  TransferData(tdGetData);

  TWindow::CloseWindow();

}


See Also

Transferring Data From a Dialog Box

Transferring Data From a Window

Transferring Data to a Window

Supporting Transfer For Customized Controls

Transferring the Data

Defining the Corresponding Window Or Dialog Box

Using Transfer with a Window


Supporting Transfer For Customized Controls (ObjectWindows)

See Also

You can modify the way a particular control transfers its data or include a new control you define in the transfer mechanism. In either case, all you need to do is to write a Transfer member function for your control object. See the following table to interpret the meaning of the transfer flag parameter.

Transfer flag parameter	Description

tdGetData	Copy data from the control to the location specified by the supplied pointer. Return the number of bytes transferred.

tdSetData	Copy the data from the transfer buffer at the supplied pointer to the control. Return the number of bytes transferred.

tdSizeData	Return the number of bytes that would be transferred.


See Also

Transferring Data From a Dialog Box

Transferring Data From a Window

Transferring Data to a Window

Transferring the Data

Combo Box Transfer

Defining the Corresponding Window Or Dialog Box

List Box Transfer

Using Transfer with a Dialog Box

Using Transfer with a Window


Gadget and Gadget Window Objects (ObjectWindows)
Gadget and Gadget Window Objects Overview (ObjectWindows)

Functionally, gadgets are similar to controls, in that they gather input from or convey information to the user. But gadgets are implemented differently from controls. Unlike most other interface elements, gadgets are not windows: they do not have window handles, do not receive events and messages, and are not based on TWindow.

Instead, gadgets must be contained in a gadget window that controls the presentation of the gadget, all message processing, and so on. The gadget receives its commands and direction from the gadget window.

To learn more about working with gadgets and the TGadget class, see

Class TGadget

To learn more about working with gadget windows, see

Gadget Windows

ObjectWindows Gadget Classes

ObjectWindows provides a number of classes derived from TGadget. These gadgets provide versatile, easy-to-use decorations and new ways to communicate with the user of your application.

To learn more about working with the classes derived from TGadget, see

Class TBitmapGadget

Class TButtonGadget

Class TControlGadget

Class TSeparatorGadget

Class TTextGadget


Class TGadget (ObjectWindows)

See Also

All gadgets are based on the TGadget class, which contains the basic functionality required by all gadgets. When you work with a gadget, you can

Construct and destroy it

Identify it

Modify and access its appearance

Set its bounds

Shrink wrap it (calculate its size automatically)

Set its size

Match its colors to the system colors

Enable and disable it

Deriving a class from TGadget

TGadget provides a number of protected access functions that you can use when deriving a gadget class from TGadget. These functions are described in

Initializing and Cleaning Up

Painting the Gadget

Invalidating and Updating the Gadget

Mouse Events in a Gadget


See Also

Gadget and Gadget Window Objects Overview

TGadget Public Data Members


Constructing and Destroying TGadget (ObjectWindows)

See Also

The TGadget constructor syntax is

TGadget(int id = 0, TBorderStyle style = None);

The following table describes the TGadget parameters:

Parameter	Description

id	An arbitrary value used as the identifier number for the gadget. You can use the identifier to identify a particular gadget in a gadget window. Other uses for the gadget identifier are discussed in Identifying a Gadget.

style 	An enum of type TBorderStyle. There are five possible values for style:

None gives the gadget no border style; that is, it has no visible borders.

Plain makes the gadget borders visible as lines, much like the border of a window frame.

Raised makes the gadget look like it is raised up from the gadget window.

Recessed makes the gadget look like it is recessed into the gadget window.

Embossed makes the gadget border look like it has an embossed ridge as a border.

The TGadget destructor is declared virtual. The only thing it does is to remove the gadget from its gadget window if that window is still valid.


See Also

Class TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Bounding the Gadget

Shrink Wrapping a Gadget

Setting Gadget Size

Matching Gadget Colors To System Colors

TGadget Public Data Members

Enabling and Disabling a Gadget

Initializing and Cleaning Up

Painting the Gadget

Invalidating and Updating the Gadget

Mouse Events in a Gadget


Identifying a Gadget (ObjectWindows)

See Also

You can identify a gadget by using the GetId function to access its identifier. GetId takes no parameters and returns an int, the gadget identifier. The identifier comes from the value passed in as the first parameter of the TGadget constructor.

There are a number of uses for the gadget identifier:

You can use the identifier to identify a particular gadget. If you have a large number of gadgets in a gadget window, the easiest way to determine which gadget is which is to use the gadget identifier.

You can set the identifier to the desired event identifier when the gadget is used to generate a command. For example, a button gadget used to open a file usually has the identifier CM_FILEOPEN.

You can set the identifier to a string identifier if you want display a text string in a message bar or status bar when the gadget is pressed. For example, suppose you have a string identifier named IDS_MYSTRING that describes your gadget. You can set the gadget identifier to IDS_MYSTRING. Then, assuming your window has a message or status bar and you have turned menu tracking on, the string IDS_MYSTRING is displayed in the message or status bar whenever you press the gadget IDS_MYSTRING.

These last two techniques are often combined. Suppose you have a command identifier CM_FILEOPEN for the File|Open menu command and a string with the resource identifier CM_FILEOPEN. If you also give the gadget the identifier CM_FILEOPEN, when you press the gadget, the gadget window posts the CM_FILEOPEN event, and the string with the resource identifier CM_FILEOPEN is displayed in the message or status bar.

You can see an illustration of this technique in Step 10 of the Learning ObjectWindows Tutorial manual.


See Also

Class TGadget

Modifying and Accessing Gadget Appearance

Constructing and Destroying TGadget

Modifying and Accessing Gadget Appearance

Bounding the Gadget

Shrink Wrapping a Gadget

Setting Gadget Size

Matching Gadget Colors To System Colors

TGadget Public Data Members

Enabling and Disabling a Gadget

Initializing and Cleaning Up

Painting the Gadget

Invalidating and Updating the Gadget

Mouse Events in a Gadget


Modifying and Accessing Gadget Appearance (ObjectWindows)

See Also

You can modify and check the margin width, border width, and border style of a gadget by using the following functions:

void SetBorders(TBorders& borders);

TBorders &GetBorders();

void SetMargins(TMargins& margins);

TMargins &GetMargins();

void SetBorderStyle(TBorderStyle style);

TBorderStyle GetBorderStyle();

The border is the outermost boundary of a gadget. The TBorders structure used with the SetBorders and GetBorders functions has four data members. These unsigned data members, Left, Right, Top, and Bottom, contain the width of the respective borders of the gadget.

The margin is the area between the border of the gadget and the inner rectangle of the gadget. The TMargins structure used with the SetMargins and GetMargins functions has four data members. These int data members, Left, Right, Top, and Bottom, contain the width of the respective margins of the gadget.

The TBorderStyle enum used with the SetBorderStyle  and GetBorderStyle functions is the same one used with the TGadget constructor. The various border style effects are achieved by painting the sides of the gadget borders and margins differently for each style.


See Also

Class TGadget

Identifying a Gadget

Constructing and Destroying TGadget

Identifying a Gadget

Bounding the Gadget

Shrink Wrapping a Gadget

Setting Gadget Size

Matching Gadget Colors To System Colors

TGadget Public Data Members

Enabling and Disabling a Gadget

Initializing and Cleaning Up

Painting the Gadget

Invalidating and Updating the Gadget

Mouse Events in a Gadget


Bounding the Gadget (ObjectWindows)

See Also

The gadget's bounding rectangle is the entire area occupied by a gadget. It is contained in a TRect structure and is composed of the relative X and Y coordinates of the upper-left and lower-right corners of the gadget in the gadget window. The gadget window uses the bounding rectangle of the gadget to place the gadget. The gadget's bounding rectangle is also important in determining when the user has clicked the gadget.

To find and set the bounding rectangle of a gadget, use the following functions:

TRect &GetBounds();

virtual void SetBounds(TRect& rect);

Note that SetBounds is declared virtual. The default SetBounds updates only the bounding rectangle data. A derived class can override SetBounds to monitor changes and update the gadget's internal state.


See Also

Class TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Constructing and Destroying TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Shrink Wrapping a Gadget

Setting Gadget Size

Matching Gadget Colors To System Colors

TGadget Public Data Members

Enabling and Disabling a Gadget

Initializing and Cleaning Up

Painting the Gadget

Invalidating and Updating the Gadget

Mouse Events in a Gadget


Shrink Wrapping a Gadget (ObjectWindows)

See Also

You can use the SetShrinkWrap function to specify whether you want the gadget window to "shrink wrap" a gadget. When shrink wrapping is on for an axis, the overall size required for the gadget is calculated automatically based on the border size, margin size, and inner rectangle. This saves you from having to calculate the bounds size of the gadget manually.

You can turn shrink wrapping on and off independently for the width and height of the gadget. The syntax of SetShrinkWrap is

void SetShrinkWrap(bool shrinkWrapWidth, bool shrinkWrapHeight);

shrinkWrapWidth turns horizontal shrink wrapping on or off, depending on whether true or false is passed in.

shrinkWrapHeight turns vertical shrink wrapping on or off, depending on whether true or false is passed in.


See Also

Class TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Constructing and Destroying TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Bounding the Gadget

Setting Gadget Size

Matching Gadget Colors To System Colors

TGadget Public Data Members

Enabling and Disabling a Gadget

Initializing and Cleaning Up

Painting the Gadget

Invalidating and Updating the Gadget

Mouse Events in a Gadget


Setting Gadget Size (ObjectWindows)

See Also

The gadget's size is the size of the bounding rectangle of the gadget. The size differs from the bounding rectangle in that it is independent of the position of the gadget. Thus, you can adjust the size of the gadget without changing the location of the gadget.

You can set the desired size of a gadget using the SetSize function,

void SetSize(TSize& size);

Changing the gadget's size effectively moves the lower right corner of the bounding rectangle.

You can get use the GetDesiredSize function to get the size the gadget would like to be:

virtual void GetDesiredSize(TSize& size);

Note: Because gadget windows can change the desired size of a gadget during the layout process, even if you have set the desired size of the gadget with SetSize, you should  call GetDesiredSize to get the gadget's desired size.


See Also

Class TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Constructing and Destroying TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Bounding the Gadget

Shrink Wrapping a Gadget

Matching Gadget Colors To System Colors

TGadget Public Data Members

Enabling and Disabling a Gadget

Initializing and Cleaning Up

Painting the Gadget

Invalidating and Updating the Gadget

Mouse Events in a Gadget


Matching Gadget Colors To System Colors (ObjectWindows)

See Also

To make your interface consistent with your application user's system, you should implement the SysColorChange function. The gadget window calls the SysColorChange function of each gadget contained in the window when the window receives a WM_SYSCOLORCHANGE message. This function has the following syntax:

virtual void SysColorChange();

The default version of SysColorChange does nothing. If you want your gadgets to follow changes in system colors, implement this function. Make sure to delete and reallocate any resources that are dependent on system color settings.


See Also

Class TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Constructing and Destroying TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Bounding the Gadget

Shrink Wrapping a Gadget

Setting Gadget Size

TGadget Public Data Members

Enabling and Disabling a Gadget

Initializing and Cleaning Up

Painting the Gadget

Invalidating and Updating the Gadget

Mouse Events in a Gadget


TGadget Public Data Members (ObjectWindows)

See Also

There are two public data members in TGadget. Both are bools:

bool Clip;

bool WideAsPossible;

The value of Clip indicates whether a clipping rectangle should be applied before painting the gadget.

The value of WideAsPossible indicates whether the gadget should be expanded to fit the available room in the window. This is useful for such things as a text gadget in a message bar.


See Also

Class TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Constructing and Destroying TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Bounding the Gadget

Shrink Wrapping a Gadget

Setting Gadget Size

Matching Gadget Colors To System Colors

Enabling and Disabling a Gadget

Initializing and Cleaning Up

Painting the Gadget

Invalidating and Updating the Gadget

Mouse Events in a Gadget


Enabling and Disabling a Gadget (ObjectWindows)

See Also

You can enable and disable a gadget using the following functions:

virtual void SetEnabled(bool);

bool GetEnabled();

Changing the state of a gadget using the default SetEnabled function causes the gadget's bounding rectangle to be invalidated, but not erased. A derived class can override SetEnabled to modify this behavior.

If your gadget generates a command, you should implement the CommandEnable function:

virtual void CommandEnable();

The default version of CommandEnable does nothing. A derived class can override this function to provide command enabling. The gadget should send a WM_COMMAND_ENABLE message to the gadget window's parent with a command-enabler object representing the gadget.

For example, here's how the CommandEnable function might be implemented:

void TMyGadget::CommandEnable()

{

  Window->Parent->HandleMessage(

    WM_COMMAND_ENABLE,

    0,

    (LPARAM) &TMyGadgetEnabler(*Window->Parent, this));

}


See Also

Class TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Constructing and Destroying TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Bounding the Gadget

Shrink Wrapping a Gadget

Setting Gadget Size

Matching Gadget Colors To System Colors

TGadget Public Data Members

Initializing and Cleaning Up

Painting the Gadget

Invalidating and Updating the Gadget

Mouse Events in a Gadget


Initializing and Cleaning Up (ObjectWindows)

See Also

TGadget provides a couple of virtual functions that give a gadget a chance to initialize or clean up:

virtual void Inserted();

virtual void Removed();

Inserted is called after inserting a gadget into a gadget window. Removed is called before removing the gadget from its gadget window. The default versions of these function do nothing.


See Also

Class TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Constructing and Destroying TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Bounding the Gadget

Shrink Wrapping a Gadget

Setting Gadget Size

Matching Gadget Colors To System Colors

TGadget Public Data Members

Enabling and Disabling a Gadget

Painting the Gadget

Invalidating and Updating the Gadget

Mouse Events in a Gadget


Painting the Gadget (ObjectWindows)

See Also

The TGadget class provides two different paint functions: PaintBorder and Paint.

The PaintBorder function paints the border of the gadget. This virtual function takes a single parameter, a TDC &, and returns void. PaintBorder implements the standard border styles. If you want to create a new border style, override this function and provide the functionality for the new style. If you want to continue to provide the standard border styles, you should also call the TGadget version of this function. PaintBorder is called by the Paint function.

The Paint function is similar to the TWindow function Paint. This function takes a single parameter, a TDC &, and returns void. Paint is declared virtual. TGadget's PaintGadgets function calls each gadget's Paint function when painting the gadget window. The default Paint function only calls the PaintBorder function. To paint the inner rectangle of the gadget's bounding rectangle, override this function and provide the necessary code.

If you are painting the gadget yourself in the Paint function, you often need to find the area inside the borders and margins of the gadget. This area is called the inner rectangle. You can find the inner rectangle using the GetInnerRect function:

void GetInnerRect(TRect& rect);

GetInnerRect places the coordinates of the inner rectangle into the TRect reference passed into it.


See Also

Class TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Constructing and Destroying TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Bounding the Gadget

Shrink Wrapping a Gadget

Setting Gadget Size

Matching Gadget Colors To System Colors

TGadget Public Data Members

Enabling and Disabling a Gadget

Initializing and Cleaning Up

Invalidating and Updating the Gadget

Mouse Events in a Gadget


Invalidating and Updating the Gadget (ObjectWindows)

See Also

Just like a window, a gadget can be invalidated. TGadget provides two functions to invalidate the gadget:

void Invalidate(bool erase = true);

void InvalidateRect(const TRect& rect, bool erase = true);

These functions are similar to the TWindow functions InvalidateRect and Invalidate. InvalidateRect looks and functions much like its Windows API version, except that it omits its HWND parameters. Invalidate invalidates the entire bounding rectangle of the gadget. It takes a single parameter, a bool indicating whether the invalid area should be erased when it is updated. By default, this parameter is true. So, to erase the entire area of your gadget, you need only call Invalidate, either specifying true or nothing at all for its parameter.

A related function is the Update function,

void Update();

This function attempts to force an immediate update of the gadget. It is similar to the Windows API UpdateWindow function.


See Also

Class TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Constructing and Destroying TGadget

Identifying a Gadget

Modifying and Accessing Gadget Appearance

Bounding the Gadget

Shrink Wrapping a Gadget

Setting Gadget Size

Matching Gadget Colors To System Colors

TGadget Public Data Members

Enabling and Disabling a Gadget

Initializing and Cleaning Up

Painting the Gadget

Mouse Events in a Gadget


Mouse Events in a Gadget (ObjectWindows)

See Also

You can track mouse events that happen inside and outside a gadget through a number of pseudo-event handlers in the TGadget class. These functions look much like standard ObjectWindows event-handling functions except that the names of the functions are not prefixed with Ev.

Because gadgets are not actually windows, they do not have response tables like other ObjectWindows classes. All of a gadget's communication with the outside is handled through the gadget window. When a mouse event takes place in the gadget window, the window tries to determine which gadget is affected by the event. To find out if an event took place inside a particular gadget, you can call the PtIn function:

virtual bool PtIn(TPoint& point);

The default behavior for this function is to return true if point is within the gadget's bounding rectangle. You could override this function if you were designing an oddly shaped gadget.

When the mouse enters the bounding rectangle of a gadget, the gadget window calls the function MouseEnter. This function looks like this:

virtual void MouseEnter(uint modKeys, TPoint& point);

modKeys contains virtual key information identical to that passed-in in the standard ObjectWindows EvMouseMove function. It indicates whether various virtual keys are pressed. This parameter can be any combination of the following values: MK_CONTROL, MK_LBUTTON, MK_MBUTTON, MK_RBUTTON, or MK_SHIFT.

point tells the gadget where the mouse entered the gadget.

After the gadget window calls the gadget's MouseEnter function to inform the gadget that the mouse has entered the gadget's area, the gadget captures mouse movements by calling the gadget window's GadgetSetCapture function to guarantee that the gadget's MouseLeave function is called.

After the mouse leaves the gadget bounds, the gadget window calls MouseLeave, which function looks like this:

virtual void MouseLeave(uint modKeys, TPoint& point);

There are also a couple of functions to detect left mouse button clicks, LButtonDown and LButtonUp. The default behavior for LButtonDown is to capture the mouse if the bool flag TrackMouse is set. The default behavior for LButtonUp is to release the mouse if the bool flag TrackMouse is set. By default TrackMouse is not set.

virtual void LButtonDown(uint modKeys, TPoint& point);

virtual void LButtonUp(uint modKeys, TPoint& point);

When the mouse is moved inside the bounding rectangle of a gadget while mouse movements are being captured by the gadget window, the window calls the gadget's MouseMove function. This function looks like this:

virtual void MouseMove(uint modKeys, TPoint& point);

As with MouseEnter, modKeys contains virtual key information. point tells the gadget where the mouse stopped moving.


See Also

Class TGadget

TGadget Public Data Members

Enabling and Disabling a Gadget

Initializing and Cleaning Up

Painting the Gadget

Invalidating and Updating the Gadget


Class TSeparatorGadget (ObjectWindows)

See Also

TSeparatorGadget is a very simple gadget. Its only function is to take up space in a gadget window. You can use it when laying other gadgets out in a window to provide a margin of space between gadgets that would otherwise be placed border-to-border in the window.

The TSeparatorGadget constructor looks like this:

TSeparatorGadget(int size = 6);

The separator disables itself and turns off shrink wrapping. The size parameter,  used for both the width and the height of the gadget, lets you use the separator gadget for both vertical and horizontal spacing.


See Also

Gadget and Gadget Window Objects Overview

Class TBitmapGadget

Class TButtonGadget

Class TControlGadget

Class TTextGadget


Class TTextGadget (ObjectWindows)
Constructing and Destroying TTextGadget (ObjectWindows)

See Also

See Also

TTextGadget is used to display text information in a gadget window. You can specify the number of characters you want to be able to display in the gadget. You can also specify how the text should be aligned in the text gadget.

For more information on working with text gadgets, see

{bmc bullet.bmp)	Constructing and Destroying TTextGadget

{bmc bullet.bmp)	Accessing the Gadget Text


See Also

Gadget and Gadget Window Objects Overview


Constructing and Destroying TTextGadget (ObjectWindows)

See Also

Here is the constructor for TTextGadget:

TTextGadget(int id = 0,

            TBorderStyle style = Recessed,

            TAlign alignment = Left,

            uint numChars = 10,

            const char* text = 0);

The constructor parameters are described in the following table:

Parameter	Description

id	The gadget identifier.

style	The gadget border style.

align 	Specifies how text should be aligned in the gadget. There are three possible values for the enum TAlign: Left, Center, and Right.

numChars 	Specifies the number of characters to be displayed in the gadget and determines gadget's width. To calculate the required gadget width, the gadget multiplies the number of characters by the maximum character width of the current font. The height of the gadget is based on the maximum character height of the current font, plus space for the margin and border.

text	A default message to be displayed in the gadget.

The destructor ~TTextGadget automatically deletes the storage for the gadget's text string.


See Also

Accessing the Gadget Text

Class TTextGadget

Gadget and Gadget Window Objects Overview


Accessing the Gadget Text (ObjectWindows)

See Also

You can get and set the text in the gadget using the TTextGadget functions GetText and SetText.

GetText takes no parameters and returns a const char *. Do not attempt to modify the gadget text through the use of the returned pointer.

SetText takes a const char * and returns void. The gadget makes a copy of the text and stores it internally.


See Also

Constructing and Destroying TTextGadget

Class TTextGadget

Gadget and Gadget Window Objects Overview


Class TBitmapGadget (ObjectWindows)

See Also

TBitmapGadget is a simple gadget that can display an array of bitmap images, one at a time. You should store the bitmaps as an array. To do this, the bitmaps should be drawn side by side in a single bitmap resource. The bitmaps should each be the same width.

With TBitmapGadget you can

Construct and destroy bitmap objects

Select a new image

Set the system colors


See Also

Gadget and Gadget Window Objects Overview

Class TButtonGadget

Class TControlGadget

Class TSeparatorGadget

Class TTextGadget


Constructing and Destroying TBitmapGadget (ObjectWindows)

See Also

Following is the constructor syntax for TBitmapGadget:

TBitmapGadget(TResId bmpResId,

              int id,

              TBorderStyle style,

              int numImages,

              int startImage);

The constructor parameters are described in the following table:

Parameter	Description

bmResId	The resource identifier for the bitmap resource.

id	The gadget identifier.

style	The gadget border style.

numImages 	The total number of images contained in the bitmap. The gadget figures the width of each single bitmap in the resource by dividing the width of the resource bitmap by numImages.

For example, suppose you pass a bitmap resource to the TBitmapGadget constructor that is 400 pixels wide by 200 pixels high, and you specify numImages as 4. The constructor would divide the bitmap resource into four separate bitmaps, each one 100 pixels wide by 200 pixels high.

startImage	Specifies which bitmap in the array should be initially displayed in the gadget.

The destructor ~TBitmapGadget deletes the storage for the bitmap images.


See Also

Gadget and Gadget Window Objects Overview

Class TBitmapGadget


Selecting a New Image (ObjectWindows)

See Also

You can change the image being displayed in a bitmap gadget with the TBitmapGadget::SelectImage function:

int SelectImage(int imageNum, bool immediate);

The imageNum parameter is the array index of the image you want displayed in the gadget. Specifying true for immediate causes the gadget to update the display immediately. Otherwise, the area is invalidated and updated when the next WM_PAINT message is received.


See Also

Gadget and Gadget Window Objects Overview

Class TBitmapGadget


Setting the System Colors with TBitmapGadget (ObjectWindows)

See Also

TBitmapGadget implements the SysColorChange function to allow the gadget's bitmaps to track the system colors. It deletes the bitmap array, calls the MapUiColors function on the bitmap resource, and then re-creates the array.


See Also

Gadget and Gadget Window Objects Overview

Class TBitmapGadget


Class TButtonGadget (ObjectWindows)

See Also

Button gadgets are the only type of gadget included in ObjectWindows that the user interacts with directly. Control gadgets also provide a gadget that receives input from the user, but they do so through a control class. The gadget in that case only acts as an intermediary between the control and gadget window.

There are three normal button gadget states: up, down, and indeterminate. In addition the button can be highlighted when pressed in all three states.

There are two basic type of button gadgets, command gadgets and setting gadgets. Setting gadgets can be exclusive (like a radio button) or non-exclusive (like a check box). Commands can only be in the up state. Settings can be in all three states.

A button gadget is pressed when the user presses the left mouse button while the cursor position is inside the gadget's bounding rectangle. The gadget is highlighted when pressed.

After the gadget has been pressed, it captures the mouse's movements. When the mouse moves outside the gadget's bounding rectangle without the left mouse button being released, highlighting is canceled but mouse movements are still captured by the gadget. The gadget is highlighted again when the mouse comes back into the gadget's bounding rectangle without the left mouse button's being released.

When the left mouse button is released, mouse movements are no longer captured. If the cursor position is inside the bounding rectangle when the button is released, the gadget identifier is posted as a command message by the gadget window.


See Also

To work with button gadgets, see:

Constructing and Destroying TButtonGadget

Accessing Button Gadget Information

Setting Button Gadget Style

Command Enabling

Setting the System Colors With TButtonGadget

For information on working with other gadgets or with gadget windows, see:

Gadget and Gadget Window Objects Overview

Class TBitmapGadget

Class TControlGadget

Class TSeparatorGadget

Class TTextGadget


Constructing and Destroying TButtonGadget (ObjectWindows)

See Also

Here is the TButtonGadget constructor:

TButtonGadget(TResId bmpResId,

              int id,

              TType type = Command,

              bool enabled = false,

              TState state = Up,

              bool repeat = false);

where:

Parameter	Description

bmpResId	The resource identifier for the bitmap resource to be displayed in the button. The size of the bitmap determines the size of the gadget, because shrink wrapping is turned on.

id	The gadget identifier. This is also the command that is posted when the gadget is pressed.

type	Specifies the type of the gadget. The TType enum has three possible values:

Command specifies that the gadget is a command,

Exclusive specifies that the gadget is an exclusive setting button. Exclusive button gadgets that are adjacent to each other work together. You can set up exclusive groups by inserting other gadgets, such as separator gadgets or text gadgets, on either side of the group.

NonExclusive specifies that the gadget is a nonexclusive setting button.

enabled 	Specifies whether or not the button gadget is enabled when it is first created. If the corresponding command is enabled when the gadget is created, the button is automatically enabled.

state	The default state of the button gadget. The enum TState can have three values: Up, Down, or Indeterminate.

repeat	Indicates whether the button repeats when held down. If repeat is true, the button repeats when it is clicked and held.

The destructor ~TButtonGadget deletes the bitmap resources and, if the resource information is contained in a string, deletes the storage for the string.


See Also

Class TButtonGadget

Gadget and Gadget Window Objects Overview


Accessing Button Gadget Information (ObjectWindows)

See Also

There are a number of TButtonGadget functions you can use to access a button gadget. These functions let you set the state of the gadget to any valid TState value, get the state of the button gadget, and get the button gadget type.

You can set the button gadget's state with the SetButtonState function:

void SetButtonState(TState);

You can find the button gadget's current state using the GetButtonState function:

TState GetButtonState();

You can find out what type of button a gadget is using the GetButtonType function:

TType GetButtonType();


See Also

Class TButtonGadget

TButtonGadget

Gadget and Gadget Window Objects Overview


Setting Button Gadget Style (ObjectWindows)

See Also

You can modify the appearance of a button gadget by using the following TButtonGadget functions:

SetNotchCorners turns corner notching on and off:

void SetNotchCorners(bool notchCorners=true);

SetAntialiasEdges turns antialiasing of the button bevels on and off:

void SetAntialiasEdges(bool anti=true);

SetShadowStyle changes the style of the button shadow. There are two options for the shadow style, both from the enum TShadowStyle: SingleShadow and DoubleShadow. Following is the syntax for SetShadowStyle:

void SetShadowStyle(TShadowStyle style=DoubleShadow);


See Also

Class TButtonGadget

Gadget and Gadget Window Objects Overview


Command Enabling (ObjectWindows)

See Also

TButtonGadget overrides the TGadget function CommandEnable. It is implemented to initiate a WM_COMMAND_ENABLE message for the gadget.

The syntax of the TButtonGadget::CommandEnable function is as follows:

void CommandEnable();


See Also

Class TButtonGadget

Gadget and Gadget Window Objects Overview


Setting the System Colors with TButtonGadget (ObjectWindows)

See Also

TButtonGadget implements the SysColorChange function to allow the gadget's bitmaps to track the system colors. It rebuilds the gadget using the system colors. If the system colors have changed, these changes are reflected in the new button gadget. The gadget  is not set up to automatically track the system colors; that is, SysColorChange is not necessarily called in response to a WM_SYSCOLORCHANGE event.


See Also

Class TButtonGadget

Gadget and Gadget Window Objects Overview


Class TControlGadget (ObjectWindows)

See Also

TControlGadget is a fairly simple class that serves as an interface between a regular Windows control (such as a button, edit box, list box, and so on) and a gadget window. It lets you use a standard Windows control in a gadget window, like a control bar, status bar, and so on.

Constructing and Destroying TControlGadget (ObjectWindows)

Here is the constructor for TControlGadget:

TControlGadget(TWindow& control, TBorderStyle style = None);

control is a reference to an ObjectWindows window object. This object should be a valid constructed control object.

style is the gadget border style.

The destructor ~TControlGadget destroys the control interface element, then deletes the storage for the control object.


See Also

Gadget and Gadget Window Objects Overview

Class TBitmapGadget

Class TButtonGadget

Class TSeparatorGadget

Class TTextGadget


Gadget Windows (ObjectWindows)

See Also

Gadget windows are based on the class TGadgetWindow, which is derived from TWindow. Gadget windows are designed to hold a number of gadgets, lay them out, and display them in another window.

Gadget windows provide a great deal of the functionality of the gadgets they contain. Because gadgets are not actually windows, they cannot post or receive events, directly interact with windows, or call Windows function for themselves. Anything that a gadget needs to be done must be done through the gadget window.

A gadget has little or no control over where it is laid out in the gadget window. The gadget window is responsible for placing and laying out all the gadgets it contains. Gadgets are generally laid in a line, either vertically or horizontally.

Gadget windows generally do not stand on their own, but instead are usually contained in another window. The most common parent window for a gadget window is a decorated frame window, such as TDecoratedFrame or TDecoratedMDIFrame, although the class TToolBox usually uses a TFloatingFrame.

To learn more about working with gadget windows, see

Constructing and Destroying TGadgetWindow

Creating a Gadget Window

Inserting a Gadget Into a Gadget Window

Removing a Gadget From a Gadget Window

Setting Window Margins and Layout Direction

Laying Out the Gadgets

Notifying the Window When a Gadget Changes Size

Shrink Wrapping a Gadget Window

Accessing the Window Font

Capturing the Mouse For a Gadget

Setting the Hint Mode

Idle Action Processing

Searching Through the Gadgets

Deriving From TGadgetWindow

ObjectWindows Gadget Window Classes


See Also

Gadget and Gadget Window Objects Overview


Constructing and Destroying TGadgetWindow (ObjectWindows)

See Also

Here is the constructor for TGadgetWindow:

TGadgetWindow(TWindow* parent = 0,

              TTileDirection direction = Horizontal,

              TFont* font = new TGadgetWindowFont,

              TModule* module = 0);

The following table describes TGadgetWindow's parameters:

Parameter	Description

parent	A pointer to the parent window object.

direction	An enum TTileDirection. There are two possible values for direction: Horizontal or Vertical.

font	A pointer to a TFont object that contains the font for the gadget window. By default, font is set to TGadgetWindowFont, which is a variable-width sans-serif font, usually Helvetica.

module 	Passed as the TModule parameter for the TWindow base constructor. This parameter defaults to 0.

The destructor ~TGadgetWindow deletes each of the gadgets contained in the gadget window and then deletes the font object.


See Also

Gadget Windows


Creating a Gadget Window (ObjectWindows)

See Also

TGadgetWindow overrides the default TWindow member function Create. The TGadgetWindow version of Create chooses the initial size based on a number of criteria:

Whether shrink wrapping was requested by any of the gadgets in the window

The size of the gadgets contained in the window

The direction of tiling in the gadget window

Whether the gadget window has a border, and the size of that border

Create determines the proper size of the window based on these factors and sets the window size attributes, then calls the base TWindow::Create to actually create the window interface element.


See Also

Gadget Windows


Inserting a Gadget Into a Gadget Window (ObjectWindows)

See Also

For a gadget window to be useful, it needs to contain some gadgets. To place a gadget into the gadget window, use the Insert function:

virtual void Insert(TGadget& gadget,

                    TPlacement placement = After,

                    TGadget* sibling = 0);

The following table describes Insert's parameters:

Parameter	Description

gadget	A reference to the gadget to be inserted into the gadget window.

placement 	Indicates where the gadget should be inserted. The enum TPlacement can have two values, Before and After. If a sibling gadget is specified by the sibling parameter, the gadget is inserted before or after the sibling, depending on the value of placement. If sibling is 0, the gadget is placed at the beginning of the gadgets in the window if placement is Before or at the end of the gadgets if placement is After.

sibling	A pointer to a sibling gadget.

If the gadget window has already been created, you need to call LayoutSession after calling Insert. Any gadget you insert will not appear in the window until the window has been laid out.


See Also

Gadget Windows


Removing a Gadget From a Gadget Window (ObjectWindows)

See Also

To remove a gadget from your gadget window, use the Remove function:

virtual TGadget* Remove(TGadget& gadget);

The gadget parameter is a reference to the gadget you want to remove from the window.

The removed gadget is returned as a TGadget *. The gadget object is not deleted. Remove returns 0 if the gadget is not in the window.

As with the Insert function, if the gadget window has already been created, you need to call LayoutSession after calling Remove. Any gadget you remove will not disappear from the window until the window has been laid out.


See Also

Gadget Windows


Setting Window Margins and Layout Direction (ObjectWindows)

See Also

You can change the margins and the layout direction of a gadget window, either before the window is created or afterwards. To do this, use the SetMargins and SetDirection functions:

void SetMargins(TMargins& margins);

virtual void SetDirection(TTileDirection direction);

Both functions set the appropriate data members, then call the function LayoutSession.

You can find out in which direction the gadgets are laid out by calling the GetDirection function:

TTileDirection GetDirection() const;


See Also

Gadget Windows


Laying Out the Gadgets (ObjectWindows)

See Also

To lay out a gadget window, call the LayoutSession function.

virtual void LayoutSession();

The default behavior of LayoutSession is to determine if the window interface element is already created. If not, the function returns without taking any further action, and the window is laid out automatically when the window element is created. But if the window element has already been created, LayoutSession tiles the gadgets and then invalidates the modified area of the gadget window.

A layout session is typically initiated by one of several actions: changing margins, inserting or removing gadgets, or changing the size of a gadget or gadget window.

The actual work of tiling the gadgets is left to the function TileGadgets:

virtual TRect TileGadgets();

TileGadgets determines the space needed for each gadget and lays each gadget out in turn. It returns a TRect containing the area of the gadget window that was modified by laying out the gadgets.

TileGadgets calls the function PositionGadget, which lets derived classes adjust the spacing between gadgets to help in implementing a custom layout scheme. The syntax of PositionGadget is

virtual void PositionGadget(TGadget* previous,
                            TGadget* next,
                            TPoint& point);

This function takes the gadgets pointed to by previous and next, figures the required spacing between the gadgets, and then fills in point. If tiling is horizontal, the relevant measure is contained in point.x. If tiling is vertical, the relevant measure is contained in point.y.


See Also

Gadget Windows


Notifying the Window When a Gadget Changes Size (ObjectWindows)

See Also

When a gadget changes size, it should call the GadgetChangedSize function for its gadget window. Here's the signature for this function:

void GadgetChangedSize(TGadget& gadget);

gadget is a reference to the gadget that changed size. The default version of this function simply initiates a layout session.


See Also

Gadget Windows


Shrink Wrapping a Gadget Window (ObjectWindows)

See Also

You can specify whether you want the gadget window to shrink wrap a gadget using the SetShrinkWrap function. Shrink wrapping for a gadget window has a slightly different meaning than for a gadget. When a gadget window is shrink wrapped for an axis, the axis' size is calculated automatically based on the desired sizes of the gadgets laid out on that axis.

You can turn shrink wrapping on and off independently for the width and height of the gadget window.

The syntax of the SetShrinkWrap function is

void SetShrinkWrap(bool shrinkWrapWidth, bool shrinkWrapHeight);

shrinkWrapWidth turns horizontal shrink wrapping on or off, depending on whether true or false is passed in.

shrinkWrapHeight turns vertical shrink wrapping on or off, depending on whether true or false is passed in.


See Also

Gadget Windows


Accessing Window Font (ObjectWindows)
Accessing the Window Font (ObjectWindows)

See Also

You can find out the current font and font size using the GetFont and GetFontHeight functions:

TFont& GetFont();

uint GetFontHeight() const;


See Also

Gadget Windows


Capturing the Mouse For a Gadget (ObjectWindows)

See Also

A gadget is always notified when the left mouse button is pressed down within its bounding rectangle. After the button is pressed, you need to capture the mouse if you want to send notification of mouse movements. You can do this using the GadgetSetCapture and GadgetReleaseCapture functions:

bool GadgetSetCapture(TGadget& gadget);

void GadgetReleaseCapture(TGadget& gadget);

The gadget parameter for both functions indicates for which gadget the window should set or release the capture. The bool returned by GadgetSetCapture indicates whether the capture was successful.

These functions are usually called by a gadget in the window through the gadget's Window pointer to its gadget window.


See Also

Gadget Windows


Setting the Hint Mode (ObjectWindows)

See Also

The hint mode of a gadget dictates when hints about the gadget are displayed by the gadget window's parent. You can set the hint mode for a gadget using the SetHintMode function:

void SetHintMode(THintMode hintMode);

The enum THintMode has three possible values:

hintMode	Display status

NoHints	Hints are not displayed.

PressHints	Hints are displayed when the gadget is pressed until the button is released.

EnterHints	Hints are displayed when the mouse passes over the gadget (when the mouse enters the gadget).

You can find the current hint mode using the GetHintMode function:

THintMode GetHintMode();

Another function, the SetHintCommand function, determines when a hint is displayed:

void SetHintCommand(int id);

This function is usually called by a gadget through the gadget's Window pointer to its gadget window, but the gadget window could also call it. Essentially, SetHintCommand simulates a menu choice, making pressing the gadget the equivalent of selecting a menu choice.

For SetHintCommand to work properly with the standard ObjectWindows classes, a number of things must be in place:

The decorated frame window parent of the gadget window must have a message or status bar.

Hints must be on in the frame window.

There must be a string resource with the same identifier as the gadget. For example, if the gadget identifier is CM_MYGADGET, you must also have a string resource defined as CM_MYGADGET.


See Also

Gadget Windows


Idle Action Processing (ObjectWindows)

See Also

Gadget windows have default idle action processing. The IdleAction function attempts to enable each gadget contained in the window by calling each gadget's CommandEnable function. The function then returns false.

IdleAction's syntax is

bool IdleAction(long idleCount);


See Also

Gadget Windows


Searching Through the Gadgets (ObjectWindows)

See Also

Use one of the following functions to search through the gadgets contained in a gadget window:

TGadget* FirstGadget() const;

TGadget* NextGadget(TGadget& gadget) const;

TGadget* GadgetFromPoint(TPoint& point) const;

TGadget* GadgetWithId(int id) const;

FirstGadget returns a pointer to the first gadget in the window's gadget list.

NextGadget returns a pointer to the next gadget in the window's gadget list. If the current gadget is the last gadget in the window, NextGadget returns 0.

GadgetFromPoint returns a pointer to the gadget that the point point is in. If point is not in a gadget, GadgetFromPoint returns 0.

GadgetWithId returns a pointer to the gadget with the gadget identifier id. If no gadget in the window has that gadget identifier, GadgetWithId returns 0.


See Also

Gadget Windows


Deriving from TGadgetWindow (ObjectWindows)

See Also

You can derive a class from TGadgetWindow to make your own specialized gadget window. TGadgetWindow provides a number of protected access functions that you can use for this purpose.

You can use these protected functions to

Paint a gadget window

Find the size of the window and the inner rectangle

Work with units of measurement

Response to messages


See Also

Gadget Windows


Painting a Gadget Window (ObjectWindows)

See Also

Just as with regular windows, TGadgetWindow implements the Paint function, as follows:

void Paint(TDC& dc, bool erase, TRect& rect);

This implementation of the Paint function selects the window's font into the device context and calls the function PaintGadgets:

virtual void PaintGadgets(TDC& dc, bool erase, TRect& rect);

PaintGadgets iterates through the gadgets in the window and requests each one to draw itself. You can override PaintGadgets to implement a custom look for your window, such as separator lines, a raised look, and so on.


See Also

Deriving from TGadgetWindow


Size and Inner Rectangle (ObjectWindows)
Finding Size of the Window and the Inner Rectangle (ObjectWindows)

See Also

Use the GetDesiredSize and GetInnerRect functions to find the overall desired size (the size needed to accommodate the borders, margins, and the widest or highest gadget) and the size and location of the window's inner rectangle.

virtual void GetDesiredSize(TSize& size);

virtual void GetInnerRect(TRect& rect);

If shrink wrapping was requested for the window, GetDesiredSize calculates the size the window needs to be to accommodate the borders, margins, and the widest or highest gadget. If shrink wrapping was not requested, GetDesiredSize uses the current width and height. The results are then placed into size.

GetInnerRect calculates the area inside the borders and margins of the window. The results are then placed into rect.

You can override GetDesiredSize and GetInnerRect to leave extra room for a custom look for your window. If you override one of these functions, you probably also need to override the other.


See Also

Deriving from TGadgetWindow


Layout Units (ObjectWindows)

See Also

You can use three different units of measurement in a gadget window:

Pixels, which are based on a single screen pixel

Layout units, which are logical units defined by dividing the window font "em" into 8 vertical and 8 horizontal segments.

Border units, which are based on the thickness of a window frame. A border unit is usually equivalent to one pixel, but it could be greater at higher screen resolutions.

It is usually best to use layout units. Because they are based on the font size, you do not have to worry about scaling your measures when you change window size or system metrics.

If you need to convert layout units to pixels, use the LayoutUnitsToPixels function:

int LayoutUnitsToPixels(int units);

The units parameter is the layout unit measure you want to convert to pixels. LayoutUnitsToPixels returns the pixel equivalent of units.

You can also convert a TMargins object to actual pixel measurements using the GetMargins function:

void GetMargins(TMargins& margins,

                int& left,

                int& right,

                int& top,

                int& bottom);

margins is the object containing the measurements you want to convert. The measurements contained in margins can be in pixels, layout units, or border units.

left, right, top, and bottom are the results of the conversion in pixels.


See Also

Deriving from TGadgetWindow


Message Response Functions (ObjectWindows)

See Also

TGadgetWindow catches the following events and implements the corresponding event-handling functions:

Response table entry	Member function

WM_CTLCOLOR	EvCtlColor

EV_WM_LBUTTONDOWN	EvLButtonDown

EV_WM_LBUTTONUP	EvLButtonUp

EV_WM_MOUSEMOVE	EvMouseMove

EV_WM_SIZE	EvSize

EV_WM_SYSCOLORCHANGE	EvSysColorChange


See Also

Deriving from TGadgetWindow


ObjectWindows Gadget Window Classes (ObjectWindows)

See Also

ObjectWindows provides several classes derived from TGadgetWindow.  that provide various ways to display and lay out gadgets. The gadget window classes are:

TControlBar

TMessageBar

TStatusBar

TToolBox


See Also

Gadget Windows


Class TControlBar (ObjectWindows)

See Also

The class TControlBar implements a control bar similar to the tool bar or control bar found along the top of the window of many popular applications. You can place any type of gadget in a control bar.

Here's the constructor for TControlBar:

TControlBar(TWindow* parent = 0,

            TTileDirection direction = Horizontal,

            TFont* font = new TGadgetWindowFont,

            TModule* module = 0);

The parameters are described in the following table:

Parameter	Description

parent	A pointer to the control bar's parent window.

direction	An enum TTileDirection. There are two possible values for direction: Horizontal or Vertical.

font	A pointer to a TFont object that contains the font for the gadget window. By default, font is set to TGadgetWindowFont, which is a variable-width sans-serif font, usually Helvetica.

module	Passed as the TModule parameter for the TWindow base constructor. Defaults to 0.


See Also

ObjectWindows Gadget Window Classes


Class TMessageBar (ObjectWindows)

See Also

TMessageBar implements a message bar with no border and one text gadget as wide as the window. It positions itself horizontally across the bottom of its parent window.

To learn more about working with message bars, see

Constructing and Destroying TMessageBar

Setting Message Bar Text

Setting the Hint Text


See Also

ObjectWindows Gadget Window Classes


Constructing and Destroying TMessageBar (ObjectWindows)

See Also

Here's the constructor for TMessageBar:

TMessageBar(TWindow*   parent = 0,

            TFont*     font = new TGadgetWindowFont,

            TModule*   module = 0);

Its parameters are described in the following table:

Parameter	Description

parent	A pointer to the message bar's parent window.

font	A pointer to a TFont object that contains the font for the gadget window. By default, font is set to TGadgetWindowFont, which is a variable-width sans-serif font, usually Helvetica.

module	Passed as the TModule parameter for the TWindow base constructor. Defaults to 0.

The destructor ~TMessageBar deletes the object's text storage.


See Also

Class TMessageBar

ObjectWindows Gadget Window Classes


Setting Message Bar Text (ObjectWindows)

See Also

Use the SetText function to set the text for a message bar text gadget:

void SetText(const char* text);

This function causes the string text to be displayed in the message bar.


See Also

Class TMessageBar

ObjectWindows Gadget Window Classes


Setting the Hint Text (ObjectWindows)

See Also

Use the SetHintText function to set the menu or command item hint text to be displayed in a raised field over a message bar:

virtual void SetHintText(const char* text);

If you pass text as 0, the hint text is cleared.


See Also

Class TMessageBar

ObjectWindows Gadget Window Classes


Class TStatusBar (ObjectWindows)

See Also

TStatusBar is similar to TMessageBar. The difference is that status bars have more options than a plain message bar, such as multiple text gadgets and reserved space for keyboard mode indicators like Caps Lock, Insert or Overwrite, and so on.

For information on working with status bars, see

Constructing and Destroying TStatusBar

Inserting Gadgets Into a Status Bar

Displaying Mode Indicators

Spacing Status Bar Gadgets


See Also

ObjectWindows Gadget Window Classes


Constructing and Destroying TStatusBar (ObjectWindows)

See Also

The syntax for the TStatusBar constructor is

TStatusBar(TWindow* parent = 0,

           TGadget::TBorderStyle borderStyle = TGadget::Recessed,

           uint modeIndicators = 0,

           TFont* font = new TGadgetWindowFont,

           TModule* module = 0);

The constructor parameters are described in the following table:

Parameter	Description

parent	A pointer to the parent window object.

style	An enum TBorderStyle.

modeIndicators	Indicates which keyboard modes can be displayed in the status bar. A defined enum type called TModeIndicator provides the following values for this parameter:

ExtendSelection
CapsLock
NumLock
ScrollLock
Overtype
RecordingMacro

These values can be ORed together to indicate multiple keyboard mode indicators.

font	A pointer to a TFont object that contains the font for the gadget window.

module	Passed as the TModule parameter for the TWindow base constructor. Defaults to 0.


See Also

Class TStatusBar

ObjectWindows Gadget Window Classes


Inserting Gadgets Into a Status Bar (ObjectWindows)

See Also

TStatusBar overrides the default Insert function. By default, the TStatusBar version adds the new gadget after the existing text gadgets but before the mode indicator gadgets.

You can place a gadget next to an existing gadget in the status bar by passing a pointer to the existing gadget in the Insert function as the new gadget's sibling. However, you cannot insert a gadget beyond the mode indicators.


See Also

Class TStatusBar

ObjectWindows Gadget Window Classes


Displaying Mode Indicators (ObjectWindows)

See Also

For a particular mode indicator to appear on the status bar, you must have specified the mode when the status bar was constructed. But once the mode indicator is on the status bar, it is up to you to make any changes in the indicator. TStatusBar provides the following functions to modify the mode indicators.

SetModeIndicator changes the status of a mode indicator to any valid arbitrary state.

void SetModeIndicator(TModeIndicator indicator, bool state);

indicator is the mode indicator you want to set. This can be any value from the enum TModeIndicator used in the constructor.

state is the state to which you want to set the mode indicator.

ToggleModeIndicator toggles a mode indicator with the  function:

void ToggleModeIndicator(TModeIndicator indicator);

indicator is the mode indicator you want to toggle. This can be any value from the enum TModeIndicator used in the constructor.


See Also

Class TStatusBar

ObjectWindows Gadget Window Classes


Spacing Status Bar Gadgets (ObjectWindows)

See Also

You can vary the spacing between mode indicator gadgets on the status bar using the SetSpacing function:

void SetSpacing(TSpacing& spacing);

spacing is a reference to a TSpacing object. TSpacing is a struct defined in the TStatusBar class. It has two data members, a TMargins::TUnits member named Units and an int named Value. The TSpacing constructor sets Units to TMargins::LayoutUnits and Value to 0.

The TSpacing struct lets you specify a unit of measurement and a number of units in a single object. When you pass this object into the SetSpacing command, the spacing between mode indicator gadgets is set to Value Units. You need to lay out the status bar before any changes take effect.


See Also

Class TMessageBar

ObjectWindows Gadget Window Classes


Class TToolBox (ObjectWindows)

See Also

TToolBox differs from the other ObjectWindows gadget window classes in that it does not arrange its gadgets in a single line. Instead, it arranges them in a matrix. The columns of the matrix are all the same width (as wide as the widest gadget) and the rows of the matrix are all the same height (as high as the highest gadget). The gadgets are arranged so that the borders overlap and are hidden under the tool box's border.

TToolBox can be created as a client window in a TFloatingFrame to produce a palette-type tool box. For an example of this, see the PAINT example in the directory EXAMPLES\OWL\OWLAPPS\PAINT.

For information on working with tool boxes, see

Constructing and Destroying TToolBox

Changing Tool Box Dimensions


See Also

ObjectWindows Gadget Window Classes


Constructing and Destroying TToolBox (ObjectWindows)

See Also

The syntax of the TToolBox constructor is

TToolBox(TWindow* parent,

         int numColumns = 2,

         int numRows = AS_MANY_AS_NEEDED,

         TTileDirection direction = Horizontal,

         TModule* module = 0);

The constructor parameters are described in the following table:

Parameter	Description

parent	A pointer to the parent window object.

numColumns	The number of columns in the tool box.

numRows	The number of rows in the tool box.

direction	An enum TTileDirection. There are two possible values for direction, Horizontal or Vertical. If direction is Horizontal, the gadgets are tiled starting at the upper left corner and moving from left to right, going down one row as each row is filled. If direction is Vertical, the gadgets are tiled starting at the upper left corner and moving down, going right one column as each column is filled.

module	Passed as the TModule parameter for the TWindow base constructor. This parameter defaults to 0.

You can specify the constant AS_MANY_AS_NEEDED for either numColumns or numRows, but not both. When you specify AS_MANY_AS_NEEDED for either parameter, the toolbox figures out how many divisions are needed based on the opposite dimension. For example, if you have twenty gadgets and you request four columns, you get five rows.


See Also

Class TToolBox

ObjectWindows Gadget Window Classes


Changing Tool Box Dimensions (ObjectWindows)

See Also

You can switch the dimensions of your tool box using the SetDirection function:

virtual void SetDirection(TTileDirection direction);

The parameter direction is an enum TTileDirection. There are two possible values for direction: Horizontal or Vertical.

If direction is not equal to the current direction for the tool box, the tool box switches its rows and columns count. For example, suppose you have a tool box that has three columns and five rows, and is laid out vertically. If you call SetDirection and set direction to Horizontal, the tool box switches rows and columns, giving it five columns and three rows.


See Also

Class TToolBox

ObjectWindows Gadget Window Classes


Printer Objects Overview (ObjectWindows)

Two ObjectWindows classes let you complete the following printing tasks:

Create a printer object

Create a printout object

Print window contents

Print a document

Choose and configure a printer

TPrinter encapsulates printer behavior and access to the printer drivers. It brings up a dialog box that lets the user select the desired printer and set the current settings for printing.

TPrintout encapsulates the actual printout. Its relationship to the printer is similar to TWindow's relationship to the screen. Drawing on the screen happens in the Paint member function of the TWindow object, while writing to the printer happens in the PrintPage member function of the TPrintout object. To print something on the printer, the application passes an instance of TPrintout to an instance of TPrinter's Print member function.


Creating a Printer Object (ObjectWindows)

See Also

Declaring TPrinter

The easiest way to create a printer object is to declare a TPrinter* in your window object that other objects in the program can use for their printing needs.

class MyWindow : public TFrameWindow

{

  .

  .

  .

  protected:

    TPrinter* Printer;

    .

    .

    .

};

Making the printer available

To make the printer available, make Printer point to an instance of TPrinter. This can be done in the constructor:

MyWindow::MyWindow(TWindow* parent, char *title)

{

  .

  .

  .

  Printer = new TPrinter;

}

You should also eliminate the printer object in the destructor:

MyWindow::~MyWindow()

{

  .

  .

  .

  delete Printer;

}

Example

Here is how it is done in the PRINTING.CPP example from directory OWLAPI\PRINTING:

class TRulerWin : public TFrameWindow

{

  .

  .

  .

  protected:

    TPrinter* Printer;

};

TRulerWin::TRulerWin(TWindow* parent, const char* title,
TModule* module)

  : TFrameWindow(parent, title, 0, false, module),

    TWindow(parent, title, module)

{

  .

  .

  .

  Printer = new TPrinter;

}

For most applications, this is sufficient. The application's main window initializes a printer object that uses the default printer specified in WIN.INI. In some cases, however, you might have applications that use different printers from different windows simultaneously. In that case, construct a printer object in the constructors of each of the appropriate windows, then change the printer device for one or more of the printers. If the program uses different printers but not at the same time, it is probably best to use the same printer object and select different printers as needed.

Note:	Although you might be tempted to override the TPrinter constructor to use a printer other than the system default, the recommended procedure is to always use the default constructor, then change the device associated with the object.


See Also

Choosing a Different Printer (ObjectWindows)

Creating a Printout Object (ObjectWindows)

Printing a Document (ObjectWindows)

Printing Window Contents (ObjectWindows)


Creating a Printout Object (ObjectWindows)

See Also

Creating a printout object is similar to writing a Paint member function for a window object: you use Windows' graphics functions to generate the image you want on a device context. Just as the window object's display context takes care of interactions with the screen device, the printout object's device context insulates you from the printer device.

Creating printout objects

Derive a new object type from TPrintout that overrides the PrintPage member function. In very simple cases, that is all you need to do.

If the document has more than one page, you must also override the HasPage member function. It must return a non-zero value as long as there is another page to be printed. The current page number is passed as a parameter to PrintPage.

The printout object has fields that hold the size of the page and a device context that is already initialized to render to the printer. The printer object sets those values by calling the printout object's SetPrintParams member function. You should use the printout object's device context in any calls to Windows graphics functions.

For Example

Here is the class TWindowPrintout, derived from TPrintout in the sample program PRINTING.CPP:

class TWindowPrintout : public TPrintout

{

  public:

    TWindowPrintout(const char* title, TWindow* window);

    void GetDialogInfo(int& minPage, int& maxPage,

                       int& selFromPage, int& selToPage);

    void PrintPage(int page, TRect& rect, unsigned flags);

    void SetBanding(bool b) {Banding = b;}

    bool HasPage(int pageNumber) {return pageNumber == 1;}

  protected:

    TWindow* Window;

    bool Scale;

};

GetDialogInfo retrieves page-range information from a dialog box if page selection is possible. Since there is only one page, GetDialogInfo for TWindowPrintout looks like this:

TWindowPrintout::GetDialogInfo(int& minPage, int& maxPage,

                               int& selFromPage, int& selToPage)

{

  minPage = 0;

  maxPage = 0;

  selFromPage = selToPage = 0;

}

PrintPage must be overridden to print the contents of each page, band (if banding is enabled), or window. PrintPage for TWindowPrintout looks like this:

void TWindowPrintout::PrintPage(int, TRect& rect, unsigned)

{

  // Conditionally scale the DC to the window so the printout

  // will resemble the window

  //

  int    prevMode;

  TSize  oldVExt, oldWExt;

  if (Scale) {

    prevMode = DC->SetMapMode(MM_ISOTROPIC);

    TRect windowSize = Window->GetClientRect();

    DC->SetViewportExt(PageSize, &oldVExt);

    DC->SetWindowExt(windowSize.Size(), &oldWExt);

    DC->IntersectClipRect(windowSize);

    DC->DPtoLP(rect, 2);

  }

  // Call the window to paint itself

  Window->Paint(*DC, false, rect);

  // Restore changes made to the DC

  if (Scale) {

    DC->SetWindowExt(oldWExt);

    DC->SetViewportExt(oldVExt);

    DC->SetMapMode(prevMode);

  }

}

SetBanding is called with banding enabled, as follows:

printout.SetBanding (true);

HasPage is called after every page is printed and by default returns false, which means that only one page will be printed. This function must be overridden to return true while pages remain in multipage documents.


See Also

Choosing a Different Printer (ObjectWindows)

Creating a Printer Object (ObjectWindows)

Printing a Document (ObjectWindows)

Printing Window Contents (ObjectWindows)


Printing Window Contents (ObjectWindows)

See Also

A simple kind of printout to generate is a copy of a window, because windows do not have multiple pages and window objects already know how to draw themselves on a device context.

Window printout objects

To create a window printout object, construct a window printout object and pass it a title string and a pointer to the window you want printed, like this:

TWindowPrintout printout("Ruler Test", this);

A printout of the Window Itself

Often you want a window to create a printout of itself in response to a menu command. Here is the message response member function that responds to the print command in PRINTING.CPP:

void TRulerWin::CmFilePrint()      // Execute File|Print command

{

  if (Printer) {

    TWindowPrintout printout("Ruler Test", this);

    printout.SetBanding(true);

    Printer->Print(this, printout, true);

  }

}

This member function calls the printer object's Print member function, which passes a pointer to the parent window and a pointer to the printout object, and specifies whether or not a printer dialog box should be displayed.

TWindowPrintout prints itself by calling your window object's Paint member function (within TWindowPrintout::PrintPage), but with a printer device context instead of a display context.


See Also

Choosing a Different Printer (ObjectWindows)

Creating a Printer Object (ObjectWindows)

Creating a Printout Object (ObjectWindows)

Printing a Document (ObjectWindows)


Printing a Document (ObjectWindows)

See Also

Windows sees a printout as a series of pages, so your printout object must turn a document into a series of page images for Windows to print. Just as you use window objects to paint images for Windows to display on the screen, you use printout objects to paint images on the printer.

Your printout object needs to be able to

Set print parameters

Count the total number of pages

Print pages

Indicate if there are more pages

Other considerations

In addition to the member functions you use doing the above tasks, printout objects have several other member functions you can override as needed. BeginPrinting and EndPrinting are called before and after any documents are printed, respectively. If you need special setup code, you can put it in BeginPrinting and undo it in EndPrinting.

Printing of pages takes place sequentially. That is, the printer calls PrintPage for each page in sequence. Before the first call to PrintPage, however, the printer object calls BeginDocument, passing the numbers of the first and last pages it prints. If your document needs to prepare to begin printing at a page other than the first, override BeginDocument. Call the corresponding member function, EndDocument, after the last page prints.

If multiple copies are printed, the multiple BeginDocument/EndDocument pairs can be called between BeginPrinting and EndPrinting.


See Also

Choosing a Different Printer (ObjectWindows)

Creating a Printer Object (ObjectWindows)

Creating a Printout Object (ObjectWindows)

Printing Window Contents (ObjectWindows)


Setting Print Parameters (ObjectWindows)

See Also

To enable your document to paginate itself, the printer object (derived from class TPrinter) calls two of the printout object's member functions: first SetPrintParams, and then GetDialogInfo.

SetPrintParams initializes page size and device-context variables in the printout object. It can also calculate any information needed to produce an efficient printout of individual pages. For example, SetPrintParams can calculate how many lines of text in the selected font can fit within the print area (using Windows API GetTextMetrics). If you override SetPrintParams, be sure to call the inherited member function, which sets the printout object's page-size and device-context defaults.


See Also

Counting Pages (ObjectWindows)

Indicating Further Pages (ObjectWindows)

Printing Each Page (ObjectWindows)


Counting Pages (ObjectWindows)

See Also

After calling SetPrintParams, the printer object calls GetDialogInfo. GetDialogInfo retrieves user page-range information from the printer dialog box. It can also be used to calculate the total number of pages based on page-size information calculated by SetPrintParams.


See Also

Indicating Further Pages (ObjectWindows)

Printing Each Page (ObjectWindows)

Setting Print Parameters (ObjectWindows)


Printing Each Page (ObjectWindows)

See Also

After the printer object has given the document a chance to paginate itself, it calls the printout object's PrintPage member function for each page to be printed. The process of printing out just the part of the document that belongs on the given page is similar to deciding which portion gets drawn on a scrolling window.

There are two issues to keep in mind when writing PrintPage member functions:

Device independence. Make sure your code does not make assumptions about scale, aspect ratio, or colors. Those properties can vary between different video and printing devices, so you should remove any device dependencies from your code.

Device capabilities. Although most video devices support all GDI operations, some printers do not. For example, many print devices, such as plotters, do not accept bitmaps at all. Others support only certain operations. When performing complex output tasks, your code should call the Windows API function GetDeviceCaps, which returns important information about the capabilities of a given output device.


See Also

Counting Pages (ObjectWindows)

Indicating Further Pages (ObjectWindows)

Setting Print Parameters (ObjectWindows)


Indicating Further Pages (ObjectWindows)

See Also

Printout objects have one last duty: to indicate to the printer object whether there are printable pages beyond a given page. The HasPage member function takes a page number as a parameter and returns a Boolean value indicating whether further pages exist. By default, HasPage returns true for the first page only. In order to print multiple pages, your printout object needs to override HasPage to return true if the document has more pages to print and false if the parameter passed is the last page.

Be sure that HasPage returns false at some point. If HasPage always returns true, printing goes into an endless loop.


See Also

Counting Pages (ObjectWindows)

Printing Each Page (ObjectWindows)

Setting Print Parameters (ObjectWindows)


Choosing a Different Printer (ObjectWindows)

See Also

You can associate the printer objects in your applications with any printer device installed in Windows. By default, TPrinter uses the Windows default printer, as specified in the [devices] section of the WIN.INI file.

There are two ways to specify an alternate printer: through a user dialog box and directly in code.

Choosing and Configuring with a User Dialog Box

A common way to assign a different printer is to bring up a dialog box that gives the user the ability to choose from a list of installed printer devices. TPrinter does this automatically when you call its Setup member function. Setup displays a dialog box based on TPrinterDialog.

One of the buttons in the printer dialog allows the user to change the printer's configuration. The Setup button brings up a configuration dialog box defined in the printer's device driver. Your application has no control over the appearance or function of the driver's configuration dialog box.

Assigning a Printer directly

In some cases, you might want to assign a specific printer device to your printer object, without user input. TPrinter has a SetPrinter member function that does just that.

SetPrinter takes three strings as parameters:  a device name, a driver name, and a port name.


See Also

Creating a Printer Object (ObjectWindows)

Creating a Printout Object (ObjectWindows)

Printing a Document (ObjectWindows)

Printing Window Contents (ObjectWindows)


Graphics Objects Overview (ObjectWindows)

ObjectWindows encapsulates the Windows Graphics Device Interface (GDI) and makes it easier to use GDI graphics objects and functions by simplifying how you create and manipulate GDI objects. From simple objects such as pens and brushes to more complex objects such as fonts and bitmaps, the GDI encapsulation of the ObjectWindows library provides a simple, consistent model for graphical programming in Windows.

See the following topics for more information on working with ObjectWindows GDI objects:

GDI Class Organization

Changes To Encapsulated GDI Functions

TBitmap Class

TBrush Class

TCursor Class

TDib Class

TFont Class

TIcon Class

TPalette Class

TPen Class

TRegion Class

Working with Device Contexts


GDI Class Organization (ObjectWindows)

See Also

There are a number of ObjectWindows classes used to encapsulate GDI functionality. Most are derived from the TGdiObject class. TGdiObject provides the common functionality for all ObjectWindows GDI classes.

TGdiObject is the abstract base class for ObjectWindows GDI objects. It provides a base destructor, an HGDIOBJ conversion operator, and the base GetObject function. It also provides orphan control for true GDI objects (that is, objects derived from TGdiObject; other GDI objects, such as TRegion, TIcon, and TDib, which are derived from TGdiBase, are known as pseudo-GDI objects).

The other classes in the ObjectWindows GDI encapsulation are:

TDC is the root class for encapsulating ObjectWindows GDI device contexts. You can create a TDC object directly or--for more specialized behavior--you can use derived classes.

TPen contains the functionality of Windows pen objects. You can construct a pen object from scratch or from an existing pen handle, pen object, or logical pen (LOGPEN) structure.

TBrush contains the functionality of Windows brush objects. You can construct a custom brush, creating a solid, styled, or patterned brush, or you can use an existing brush handle, brush object, or logical brush (LOGBRUSH) structure.

TFont lets you easily use Windows fonts. You can construct a font with custom specifications, or from an existing font handle, font object, or logical font (LOGFONT) structure.

TPalette encapsulates a GDI palette. You can construct a new palette or use existing palettes from various color table types that are used by DIBs.

TBitmap contains Windows bitmaps. You can construct a bitmap from many sources, including files, bitmap handles, application resources, and more.

TRegion defines a region in a window. You can construct a region in numerous shapes, including rectangles, ellipses, and polygons. TRegion is a pseudo-GDI object; it is not derived from TGdiObject.

TIcon encapsulates Windows icons. You can construct an icon from a resource or explicit information. TIcon is a pseudo-GDI object.

TCursor encapsulates the Windows cursor. You can construct a cursor from a resource or explicit information.

TDib encapsulates the device-independent bitmap (DIB) class. DIBs have no Windows handle; instead they are just a structure containing format and palette information and a collection of bits (pixels). This class provides a convenient way to work with DIBs like any other GDI object. A DIB is what is really inside a .BMP file, in bitmap resources, and what is put on the Clipboard as a DIB. TDib is a pseudo-GDI object.


See Also

Changes To Encapsulated GDI Functions

Graphics Objects Overview

TBitmap Class

TBrush Class

TCursor Class

TDib Class

TFont Class

TIcon Class

TPalette Class

TPen Class

TRegion Class

Working with Device Contexts


Changes To Encapsulated GDI Functions (ObjectWindows)

See Also

Many of the functions in the ObjectWindows GDI classes might look familiar to you; this is because many of them have the same names and very nearly, if not exactly, the same function signature as regular Windows API functions. Because the ObjectWindows GDI classes replicate the functionality of so many Windows objects, there was no need to alter the existing terminology. Therefore, function names and signatures have been deliberately kept as close as possible to what you are used to in the standard Windows GDI functions.

Some improvements, however, have been made to the functions. These improvements include such things as cracking packed return values and using ObjectWindows objects in place of Windows-defined structures.

None of these changes are hard and fast rules; just because a function can somehow be converted does not mean it necessarily has been. But if you see an ObjectWindows function with the same name as a Windows API function that looks a little different, one of the following reasons should explain the change to you:

API functions that take an object handle as a parameter often omit the handle in the ObjectWindows version.

The TGdiObject base object maintains a handle to each object. The ObjectWindows version then uses that handle when passing the call on to Windows. For example, when selecting an object in a device context, you would normally use the SelectObject API function, as shown here:

void SelectPen(HDC& hdc, HPEN& hpen)

{

  HPEN hpenOld;

  hpenOld = SelectObject(hdc, hpen);

  // Do something with the new pen.

  .

  .

  .

  // Now select the old pen again.

  SelectObject(hdc, hpenOld);

}

The ObjectWindows version of this function is encapsulated in the TDC class, which is derived from TGdiObject. The following example shows how the previous function would appear in a member function of a TDC-derived class. Notice the difference between the two calls to SelectObject:

void SelectPen(TDC& dc, TPEN& pen)

{

  dc.SelectObject(pen);

  // Do something with the new pen.

  .

  .

  .

  // Now select the old pen again.

  dc.RestorePen();

  }

ObjectWindows GDI functions usually substitute an ObjectWindows type in place of a Windows type.

Windows API functions use individual parameters to specify x and y coordinate values; ObjectWindows GDI functions use TPoint objects.

Windows API functions use RECT structures to specify a rectangular area; ObjectWindows GDI functions use TRect objects.

Windows API functions use RGN structures to specify a region; ObjectWindows GDI functions use TRegion objects.

Windows API functions take HLOCAL or HGLOBAL parameters to pass an object that does not have a predefined Windows structure; ObjectWindows GDI functions use references to ObjectWindows objects.

Some Windows functions return a uint32 with data encoded in it.

The uint32 must then must be cracked to get the data from it. The ObjectWindows versions of these functions take a reference to some appropriate object as a parameter. The function then places the data into the object, relieving the programmer from the responsibility of cracking the value. These functions usually return a bool, indicating whether the function call was successful.

For example, the Windows version of SetViewportOrg returns a uint32, with the old value for the viewport origin contained in it. The ObjectWindows version of SetViewportOrg takes a TPoint reference in place of the two ints the Windows version takes as parameters. It also takes a second parameter, a TPoint *, in which the old viewport origins are placed.


See Also

GDI Class Organization

Graphics Objects Overview

TBitmap Class

TBrush Class

TCursor Class

TDib Class

TFont Class

TIcon Class

TPalette Class

TPen Class

TRegion Class

Working with Device Contexts


Working with Device Contexts (ObjectWindows)

See Also

When working with the Windows GDI, you use a device context to access all devices, from windows to printers to plotters. The device context is a structure maintained by GDI that contains essential information about the device with which you are working, such as the default foreground and background colors, font, palette, and so on. ObjectWindows encapsulates device-context information in a number of DC classes, all of which are based on the TDC class.

TDC contains most of the device-context functionality you might require. The other DC-related classes are derived from TDC or TDC-derived classes. These derived classes only specialize the functionality of the TDC class and apply it to a discrete set of operations. Here is a description of each of the device-context classes:

TDC is the root class for all GDI device contexts for ObjectWindows; it can be instantiated itself or specialized subclasses can be used to get specific behavior.

TWindowDC provides access to the entire area owned by a window; this is the base for any DC class that releases its handle when done.

TScreenDC provides direct access to the screen bitmap using a device context for window handle 0, which is for the whole screen with no clipping.

TDesktopDC provides access to the desktop window's client area, which is the screen behind all other windows.

TClientDC provides access to the client area owned by a window.

TPaintDC wraps BeginPaint and EndPaint calls for use in an WM_PAINT response function.

TMetaFileDC provides a device context with a metafile loaded for use.

TCreatedDC lets you create a device context for a specified device.

TIC lets you create an information context for a specified device.

TMemoryDC provides access to a memory device context.

TDibDC provides access to DIBs using the DIB.DRV driver.

TPrintDC provides access to a printer device context.


See Also

Changes To Encapsulated GDI Functions

GDI Class Organization

Graphics Objects Overview

TBitmap Class

TBrush Class

TCursor Class

TDib Class

TFont Class

TIcon Class

TPalette Class

TPen Class

TRegion Class


TDC Class (ObjectWindows)

See Also

Although the specialized device-context classes provide extra functionality tailored to each class' specific purpose, the TDC class provides most of each class' functionality.

Many of the TDC functions look much like Windows API functions and are therefore described only briefly.

To learn more about TDC class, review the following topics:

Clip and Update Rectangle and Region Functions

Color and Palette Functions

Constructing and Destroying TDC

Coordinate Functions

Current Position Functions

Device-context functions

Device-context operators

Drawing Attribute Functions

Drawing Tool Functions

Font Functions

MetaFile Functions

Object Data Members and Functions

Output Functions

Path Functions

Selecting and Restoring GDI Objects

Viewport and Window Mapping Functions


See Also

Changes To Encapsulated GDI Functions

GDI Class Organization

Graphics Objects

TBitmap Class

TBrush Class

TCursor Class

TDib Class

TFont Class

TIcon Class

TPalette Class

TPen Class

TRegion Class

Working with Device Contexts


Constructing and Destructing TDC (ObjectWindows)
Constructing and Destroying TDC (ObjectWindows)

See Also

TDC provides one public constructor and one public destructor. The public constructor takes an HDC, a handle to a device context. Essentially this means that you must have an existing device context before constructing a TDC object. Usually you do not construct a TDC directly, even though you can. Instead you usually use a TDC object when passing some device context as a function parameter or a pointer to a TDC to point to some device context contained in either a TDC or TDC-derived object.

The destructor ~TDC restores all the default objects in the device context and discards the objects.

TDC also provides two protected constructors for use by derived classes. The first is a default constructor so that derived classes do not have to explicitly call TDC's constructor. The second takes an HDC and a TAutoDelete flag. TAutoDelete is an enum that can be NoAutoDelete or AutoDelete. The TAutoDelete parameter is used to initialize the ShouldDelete member, which is inherited from TGdiObject (the public TDC constructor initializes this to NoAutoDelete).


See Also

Clip and Update Rectangle and Region Functions

Color and Palette Functions

Coordinate Functions

Current Position Functions

Device-context functions

Device-context operators

Drawing Attribute Functions

Drawing Tool Functions

Font Functions

MetaFile Functions

Output Functions

Path Functions

Selecting and Restoring GDI Objects

Viewport and Window Mapping Functions


DC Operators (ObjectWindows)
Device-context Operators (ObjectWindows)

See Also

TDC provides one conversion operator, HDC, that lets you return the handle to the device context of your particular TDC or TDC-derived object. This operator is most often invoked implicitly. When you use a TDC object where you would normally use an HDC, such as in a function call or the like, the compiler tries to find a way to cast the object to the required type. Thus it uses the HDC conversion operator even though it is not explicitly called.

For example, suppose you want to create a device context in memory that is compatible with the device associated with a TDC object. You can use the CreateCompatibleDC Windows API function to create the new DC from your existing TDC object:

HDC GetCompatDC(TDC& dc, TWindow& window)

{

  HDC compatDC;

  if(!(compatDC = CreateCompatibleDC(dc)))

  {

    window.MessageBox("Couldn't create compatible device context!",

                      "Failure",

                      MB_OK | MB_ICONEXCLAMATION);

    return NULL;

  }

  else return compatDC;

}

Notice that CreateCompatibleDC takes a single parameter, an HDC. Thus the function parameter dc is implicitly cast to an HDC in the CreateCompatibleDC call.


See Also

Clip and Update Rectangle and Region Functions

Color and Palette Functions

Constructing and Destroying TDC

Coordinate Functions

Current Position Functions

Device-context functions

Drawing Attribute Functions

Drawing Tool Functions

Font Functions

MetaFile Functions

Output Functions

Path Functions

Selecting and Restoring GDI Objects

Viewport and Window Mapping Functions


DC Functions (ObjectWindows)
Device-context functions (ObjectWindows)

See Also

The device-context functions are used to access information about the device context (DC) itself. They are equivalent to the Windows API functions of the same names.

You can save and restore a device context much as you would with the Windows API by using the functions SaveDC and RestoreDC. The following code sample shows how these functions might be used. Notice that RestoreDC's single parameter uses a default value instead of specifying the int parameter:

void TMyDC::SomeFunc(TDC& dc, int x1, int y1, int x2, int y2)

{

  dc.SaveDC();

  dc.SetMapMode(MM_LOENGLISH);

  .

  .

  .

  dc.Rectangle(x1, -y1, x2, -y2);

  dc.RestoreDC();

}

You can also reset a device context to the settings contained in a DEVMODE structure using the ResetDC function. The only parameter ResetDC takes is a reference to a DEVMODE structure.

You can use the GetDeviceCaps function to retrieve device-specific information about a given display device. This function takes one parameter, an int index to the type of information to retrieve from the device context. The possible values for this parameter are the same as for the Windows API function.

You can use the GetDCOrg function to locate the current device context's logical coordinates within the display device's absolute physical coordinates. This function takes a reference to a TPoint structure and returns a bool. The bool indicates whether the function call was successful, and the TPoint object contains the coordinates of the device context's translation origin.


See Also

Clip and Update Rectangle and Region Functions

Color and Palette Functions

Constructing and Destroying TDC

Coordinate Functions

Current Position Functions

Device-context operators

Drawing Attribute Functions

Drawing Tool Functions

Font Functions

MetaFile Functions

Output Functions

Path Functions

Selecting and Restoring GDI Objects

Viewport and Window Mapping Functions


Selecting and Restoring GDI Objects (ObjectWindows)

See Also

You can use the SelectObject function to place a GDI object into a device context. There are four versions of the SelectObject function; all of them return void, but each takes different parameters. The version you should use depends on the type of object you are selecting into the device context. The different versions are:

SelectObject(const TBrush& brush);

SelectObject(const TPen& pen);

SelectObject(const TFont& font);

SelectObject(const TPalette& palette, bool forceBG=false);

In addition, TMemoryDC lets you select a bitmap.

Graphics objects that you can select into a device context normally exist as logical objects, which contain the information required for the creation of the object. The graphics objects are connected to the logical objects through a Windows handle. When the graphics object is selected into the device context, a physical tool (created using the attributes contained in the logical pen) is created inside the device context.

You can also select a stock object using the function SelectStockObject. SelectStockObject takes one parameter, an int that is equivalent to the parameter used to call the API function GetStockObject. Essentially the SelectStockObject function takes the place of two calls: a call to GetStockObject to actually get a stock object, then a call to SelectObject to place the stock object into the device context.

TDC provides functions to restore original objects in a device context. There are normally four versions of this function, RestoreBrush, RestorePen, RestoreFont, and RestorePalette. A fifth, RestoreTextBrush, exists only for 32-bit applications. The RestoreObjects function calls all four functions (or five, under 32 bits), and restores all original objects in the device context. All of these functions return void and take no parameters.


See Also

Clip and Update Rectangle and Region Functions

Color and Palette Functions

Constructing and Destroying TDC

Coordinate Functions

Current Position Functions

Device-context functions

Device-context operators

Drawing Attribute Functions

Drawing Tool Functions

Font Functions

MetaFile Functions

Output Functions

Path Functions

Viewport and Window Mapping Functions


Drawing Tool Functions (ObjectWindows)

See Also

GetBrushOrg takes one parameter, a reference to a TPoint object. It places the coordinates of the brush origin into the TPoint object. GetBrushOrg returns true if the operation was successful.

SetBrushOrg takes two parameters, a reference to a TPoint object and a TPoint *, and sets the device context's brush origin to the x and y values in the first TPoint object. If you do not specify a value for the second parameter, it defaults to 0. If you do pass a pointer to a TPoint object as the second parameter, SetBrushOrg places the old values for the brush origin into the x and y members of the object. The return value indicates whether the operation was successful.


See Also

Clip and Update Rectangle and Region Functions

Color and Palette Functions

Constructing and Destroying TDC

Coordinate Functions

Current Position Functions

Device-context functions

Device-context operators

Drawing Attribute Functions

Font Functions

MetaFile Functions

Output Functions

Path Functions

Selecting and Restoring GDI Objects

Viewport and Window Mapping Functions


Color and Palette Functions (ObjectWindows)

See Also

TDC provides a number of functions you can use to manipulate the colors and palette of a device context.

RealizePalette

GetNearestColor

SetSystemPaletteUse

GetSystemPaletteEntries

UpdateColors

GetSystemPaletteUse


See Also

Clip and Update Rectangle and Region Functions

Constructing and Destroying TDC

Coordinate Functions

Current Position Functions

Device-context functions

Device-context operators

Drawing Attribute Functions

Drawing Tool Functions

Font Functions

MetaFile Functions

Output Functions

Path Functions

Selecting and Restoring GDI Objects

Viewport and Window Mapping Functions


Drawing Attribute Functions (ObjectWindows)

See Also

Use drawing attribute functions to set the device context's drawing mode. All these functions are analogous to the API functions of the same names, except that the HDC parameter is omitted in each.

SetBkColor

GetBkColor

SetBkMode

GetBkMode

SetPolyFillMode

GetPolyFillMode

SetROP2

GetROP2

SetStretchBltMode

GetStretchBltMode

SetTextColor

GetTextColor

Another function, SetMiterLimit, is available only for 32-bit applications.


See Also

Clip and Update Rectangle and Region Functions

Color and Palette Functions

Constructing and Destroying TDC

Coordinate Functions

Current Position Functions

Device-context functions

Device-context operators

Drawing Tool Functions

Font Functions

MetaFile Functions

Output Functions

Path Functions

Selecting and Restoring GDI Objects

Viewport and Window Mapping Functions


Viewport and Window Mapping Functions (ObjectWindows)

See Also

Use these functions to set the viewport and window mapping modes:

GetMapMode

GetViewportExt

GetViewportOrg

GetWindowExt

GetWindowOrg

OffsetViewportOrg

OffsetWindowOrg

ScaleViewportExt

ScaleWindowExt

SetMapMode

SetViewportExt

SetViewportOrg

SetWindowExt

SetWindowOrg

The following viewport and window mapping functions are available only for 32-bit applications:

ModifyWorldTransform

SetWorldTransform


See Also

Clip and Update Rectangle and Region Functions

Color and Palette Functions

Constructing and Destroying TDC

Coordinate Functions

Current Position Functions

Device-context functions

Device-context operators

Drawing Attribute Functions

Drawing Tool Functions

Font Functions

MetaFile Functions

Output Functions

Path Functions

Selecting and Restoring GDI Objects


Coordinate Functions (ObjectWindows)

See Also

Coordinate functions convert logical coordinates to physical coordinates and vice versa:

LPtoDP

DPtoLP


See Also

Clip and Update Rectangle and Region Functions

Color and Palette Functions

Constructing and Destroying TDC

Current Position Functions

Device-context functions

Device-context operators

Drawing Attribute Functions

Drawing Tool Functions

Font Functions

MetaFile Functions

Output Functions

Path Functions

Selecting and Restoring GDI Objects

Viewport and Window Mapping Functions


Clip and Update Rectangle and Region Functions (ObjectWindows)

See Also

Use clip and update rectangle and region functions to set up and retrieve simple or complex areas in a device context's clipping region:

OffsetClipRgn

ExcludeClipRect

PtVisible

ExcludeUpdateRgn

RectVisible

GetBoundsRect

SelectClipRgn

GetClipBox

SetBoundsRect

GetClipRgn

IntersectClipRect


See Also

Color and Palette Functions

Constructing and Destroying TDC

Coordinate Functions

Current Position Functions

Device-context functions

Device-context operators

Drawing Attribute Functions

Drawing Tool Functions

Font Functions

MetaFile Functions

Output Functions

Path Functions

Selecting and Restoring GDI Objects

Viewport and Window Mapping Functions


MetaFile Functions (ObjectWindows)

See Also

Use the metafile functions to access metafiles:

PlayMetaFileRecord

EnumMetaFile

PlayMetaFile


See Also

Clip and Update Rectangle and Region Functions

Color and Palette Functions

Constructing and Destroying TDC

Coordinate Functions

Current Position Functions

Device-context functions

Device-context operators

Drawing Attribute Functions

Drawing Tool Functions

Font Functions

Output Functions

Path Functions

Selecting and Restoring GDI Objects

Viewport and Window Mapping Functions


Current Position Functions (ObjectWindows)

See Also

GetCurrentPosition  takes a reference to a TPoint object. It places the coordinates of the current position into the TPoint object and returns true if the function call was successful.

Use the MoveTo functions to move to the current point in the device context. Three versions of MoveTo are provided:

MoveTo(int x, int y) moves the pen to the point x, y.

MoveTo(TPoint &point) moves the pen to the point point.x, point.y.

MoveTo(TPoint &point, TPoint &oldPoint) moves the pen to the point point.x, point.y and places the old location of the pen into oldPoint.


See Also

Clip and Update Rectangle and Region Functions

Color and Palette Functions

Constructing and Destroying TDC

Coordinate Functions

Device-context functions

Device-context operators

Drawing Attribute Functions

Drawing Tool Functions

Font Functions

MetaFile Functions

Output Functions

Path Functions

Selecting and Restoring GDI Objects

Viewport and Window Mapping Functions


Font Functions (ObjectWindows)

See Also

Use TDC's font functions to access and manipulate fonts:

GetCharWidth

EnumFontFamilies

GetFontData

EnumFonts

SetMapperFlags

GetAspectRatioFilter

GetCharABCWidths


See Also

Clip and Update Rectangle and Region Functions

Color and Palette Functions

Constructing and Destroying TDC

Coordinate Functions

Current Position Functions

Device-context functions

Device-context operators

Drawing Attribute Functions

Drawing Tool Functions

MetaFile Functions

Output Functions

Path Functions

Selecting and Restoring GDI Objects

Viewport and Window Mapping Functions


Path Functions (ObjectWindows)

See Also

Path functions are available only to 32-bit applications. The TDC path functions are the same as the Win32 versions, with the exception that the TDC versions do not take a HDC parameter.

PathToRegion

BeginPath

SelectClipPath

CloseFigure

StrokeAndFillPath

EndPath

StrokePath

FillPath

WidenPath

FlattenPath


See Also

Clip and Update Rectangle and Region Functions

Color and Palette Functions

Constructing and Destroying TDC

Coordinate Functions

Current Position Functions

Device-context functions

Device-context operators

Drawing Attribute Functions

Drawing Tool Functions

Font Functions

MetaFile Functions

Output Functions

Selecting and Restoring GDI Objects

Viewport and Window Mapping Functions


Output Functions (ObjectWindows)

See Also

TDC provides a great variety of output functions for all different kinds of objects that a standard device context can handle, including:

Icons

Bitmaps

Rectangles

Text

Regions

Shapes

Nearly all these functions provide a number of versions: one version that provides functionality nearly identical to that of the corresponding API function (with the exception of omitting the HDC parameter) and alternate versions that use TPoint, TRect, TRegion, and other ObjectWindows data encapsulations to make the calls more concise and easier to understand.

Current position

MoveTo

GetCurrentPosition

Icons

DrawIcon

Rectangles

InvertRect

DrawFocusRect

TextRect

FillRect

FrameRect

Regions

InvertRgn

FillRgn

PaintRgn

FrameRgn

Shapes

Arc

Chord

Ellipse

Pie

LineTo

Polygon

Polyline

PolyPolygon

Rectangle

RoundRect

Bitmaps and blitting

BitBlt

ExtFloodFill

FloodFill

GetDIBits

GetPixel

PatBlt

ScrollDC

SetDIBits

SetDIBitsToDevice

SetPixel

StretchBlt

StretchDIBits

Text

DrawText

ExtTextOut

GrayString

TabbedTextOut

TextOut

The following functions are available for 32-bit applications only:

Shapes

AngleArc

PolyBezier

PolyBezierTo

PolyDraw

PolylineTo

PolyPolyline

Bitmaps and blitting

MaskBlt

PlgBlt


See Also

Clip and Update Rectangle and Region Functions

Color and Palette Functions

Constructing and Destroying TDC

Coordinate Functions

Current Position Functions

Device-context functions

Device-context operators

Drawing Attribute Functions

Drawing Tool Functions

Font Functions

MetaFile Functions

Path Functions

Selecting and Restoring GDI Objects

Viewport and Window Mapping Functions


Object Data Members and Functions (ObjectWindows)

See Also

These data members and functions are used to administer the device context object itself. They are protected and can be accessed only by a TDC-derived class.

ShouldDelete  indicates whether the object should delete its handle to the device context when the destructor is invoked.

Handle contains the actual handle of the device context.

OrgBrush, OrgPen, OrgFont, and OrgPalette are the handles to the original objects when the device context was created. OrgTextBrush is also present in 32-bit applications.

CheckValid throws an exception if the device context object is not valid.

Init sets OrgBrush, OrgPen, OrgFont, and OrgPalette when the object is created. If you're creating a TDC-derived class without explicitly calling a TDC constructor, you should call TDC::Init first in your constructor.

GetHDC returns an HDC using Handle.

GetAttributeHDC, like GetHDC, returns an HDC using Handle. If you're creating an object with more than one device context, you should override this function and not GetHDC to provide the proper return.

OWLFastWindowFrame draws a frame that is often used for window borders. This function uses the undocumented Windows API function FastWindowFrame if available, or PatBlt if not.


See Also

Clip and Update Rectangle and Region Functions

Color and Palette Functions

Constructing and Destroying TDC

Coordinate Functions

Current Position Functions

Device-context functions

Device-context operators

Drawing Attribute Functions

Drawing Tool Functions

Font Functions

MetaFile Functions

Path Functions

Selecting and Restoring GDI Objects

Viewport and Window Mapping Functions

TDC Class


TPen Class (ObjectWindows)

See Also

The TPen class encapsulates a logical pen. It contains a color for the pen's "ink" (encapsulated in a TColor object), a pen width, and the pen style.

To learn more about TPen class, review the following topics:

Constructing TPen

Accessing TPen


See Also

Changes To Encapsulated GDI Functions

GDI Class Organization

Graphics Objects Overview

TBitmap Class

TBrush Class

TCursor Class

TDib Class

TFont Class

TIcon Class

TPalette Class

TRegion Class

Working with Device Contexts


Constructing TPen (ObjectWindows)

See Also

You can construct a TPen either directly, by specifying the color, width, and style of the pen, or indirectly, by specifying a TPen & or pointer to a LOGPEN structure. Directly constructing a pen creates a new object with the specified attributes. Here is the constructor for directly constructing a pen:

TPen(TColor color, int width=1, int style=PS_SOLID);

The style parameter can be one of the following values: PS_SOLID, PS_DASH, PS_DOT, PS_DASHDOT, PS_DASHDOTDOT, PS_NULL, or PS_INSIDEFRAME.

Indirectly creating a pen creates a new object, but copies the attributes of the object passed to it into the new pen object. Here are the constructors for indirectly creating a pen:

TPen(const LOGPEN far* logPen);

TPen(const TPen&);

You can also create a new TPen object from an existing HPEN handle:

TPen(HPEN handle, TAutoDelete autoDelete = NoAutoDelete);

This constructor is used to obtain an ObjectWindows object as an alias to a regular Windows handle received in a message.

Two other constructors are available only for 32-bit applications. You can use these constructors to create cosmetic or geometric pens:

TPen(uint32 penStyle,

     uint32 width,

     const TBrush& brush,

     uint32 styleCount,

     LPDWORD style);

TPen(uint32 penStyle,

     uint32 width,

     const LOGBRUSH& logBrush,

     uint32 styleCount,

     LPDWORD style);

where:

penStyle is a combination of type, style, end cap, and join of the pen, where:

Type is either PS_GEOMETRIC or PS_COSMETIC.

Style can be any one of the following values:

PS_ALTERNATE

PS_DASH

PS_DASHDOT

PS_DASHDOTDOT

PS_DOT

PS_INSIDEFRAME

PS_NULL

PS_SOLID

PS_USERSTYLE

End cap is specified only for geometric pens, and can be one of the following values:

PS_ENDCAP_FLAT

PS_ENDCAP_ROUND

PS_ENDCAP_SQUARE

Join is specified only for geometric pens, and can be one of the following values:

PS_JOIN_BEVEL

PS_JOIN_MITER

PS_JOIN_ROUND

width is the pen width.

brush or logBrush is a reference to an existing TBrush or LOGBRUSH object.

styleCount is the size (in uint32s) of the style array and should be 0 unless the pen style is PS_USERSTYLE.

style is a pointer to an array of uint32s that specifies the pattern of the pen and should be NULL unless the pen style is PS_USERSTYLE.


See Also

Accessing TPen

TPen Class


Accessing TPen (ObjectWindows)

See Also

You can access TPen through an HPEN or as a LOGPEN structure. To get an HPEN from a TPen object, use the HPEN() operator with the TPen object as the parameter. The HPEN() operator is almost never explicitly invoked.

HPEN GetHPen(TPen& pen)

{

  return pen;

}

This code automatically invokes the HPEN() conversion operator to cast the TPen object to the correct type.

To convert a TPen object to a LOGPEN structure, use the GetObject function:

bool GetLogPen(LOGPEN far& logPen)

{

  TPen pen(TColor::LtMagenta, 10);

  return pen.GetObject(logPen);

}

The following example shows how to use a pen with a TDC to draw a line:

void

TPenDemo::DrawLine(TDC& dc, const TPoint& point, TColor& color)

{

  TPen BrushPen(color, PenSize);

  dc.SelectObject(BrushPen);

  dc.LineTo(point);

}


See Also

Constructing TPen

TPen Class


TBrush Class (ObjectWindows)

See Also

The TBrush class encapsulates a logical brush. It contains a color for the brush's ink (encapsulated in a TColor object), a brush width, and, depending on how the brush is constructed, the brush style, pattern, or bitmap.

To learn more about TBrush, review the following topics:

Constructing TBrush

Accessing TBrush


See Also

Changes To Encapsulated GDI Functions

GDI Class Organization

Graphics Objects Overview

TBitmap Class

TCursor Class

TDib Class

TFont Class

TIcon Class

TPalette Class

TPen Class

TRegion Class

Working with Device Contexts


Constructing TBrush (ObjectWindows)

See Also

You can construct a TBrush either directly, by specifying the color, width, and style of the brush, or indirectly, by specifying a TBrush & or a pointer to a LOGBRUSH structure. Directly constructing a brush creates a new object with the specified attributes. Here are the constructors for directly constructing a brush:

TBrush(TColor color);

TBrush(TColor color, int style);

TBrush(const TBitmap& pattern);

TBrush(const TDib& pattern);

The first constructor creates a solid brush with the color contained in color.

The second constructor creates a hatched brush with the color contained in color and the hatch style contained in style. style can be one of the following values:

HS_BDIAGONAL

HS_CROSS

HS_DIAGCROSS

HS_FDIAGONAL

HS_HORIZONTAL

HS_VERTICAL

The third and fourth constructors create a brush from the bitmap or DIB passed as a parameter. The width of the brush depends on the size of the bitmap or DIB.

Indirectly creating a brush also creates a new object, but copies the attributes of the object passed to it into the new brush object. Here are the constructors for indirectly creating a brush:

TBrush(const LOGBRUSH far* logBrush);

TBrush(const TBrush& src);

You can also create a new TBrush object from an existing HBRUSH handle:

TBrush(HBRUSH handle, TAutoDelete autoDelete = NoAutoDelete);

This constructor is used to obtain an ObjectWindows object as an alias to a regular Windows handle received in a message.


See Also

Accessing TBrush

TBrush Class


Accessing TBrush (ObjectWindows)

See Also

You can access TBrush through an HBRUSH or as a LOGBRUSH structure. To get an HBRUSH from a TBrush object, use the HBRUSH() operator with the TBrush object as the parameter. The HBRUSH() operator, listed below, is almost never explicitly invoked:

HBRUSH GetHBrush(TBrush& brush)

{

  return brush;

}

This code automatically invokes the HBRUSH() conversion operator to cast the TBrush object to the correct type.

To convert a TBrush object to a LOGBRUSH structure, use the GetObject function:

bool GetLogBrush(LOGBRUSH far& logBrush)

{

  TBrush brush(TColor::LtCyan, HS_DIAGCROSS);

  return brush.GetObject(logBrush);

}

To reset the origin of a brush object, use the UnrealizeObject function, which resets the brush's origin and returns a nonzero value if successful.

The following code shows how to use a brush to paint a rectangle in a window:

void

TMyWindow::PaintRect(TDC& dc, TPoint& p, TSize& size)

{

  TBrush brush(TColor(5,5,5));

  dc.SelectObject(brush);

  dc.Rectangle(p, size);

  dc.RestoreBrush();

}


See Also

Constructing TBrush


TFont Class (ObjectWindows)

See Also

The TFont class lets you easily create and use Windows fonts in your applications. It encapsulates all attributes of a logical font.

To learn more about TFont, review the following topics:

Constructing TFont

Accessing TFont


See Also

Changes To Encapsulated GDI Functions

GDI Class Organization

Graphics Objects Overview

TBitmap Class

TBrush Class

TCursor Class

TDib Class

TIcon Class

TPalette Class

TPen Class

TRegion Class

Working with Device Contexts


Constructing TFont (ObjectWindows)

See Also

You can construct a TFont either directly, by specifying all the attributes of the font in the constructor, or indirectly, by specifying a TFont & or a pointer to a LOGFONT structure. Directly constructing a pen creates a new object with the specified attributes. Here are the constructors for directly constructing a font:

TFont(const char far* facename=0,

      int height=0, int width=0, int escapement=0,

      int orientation=0, int weight=FW_NORMAL,

      uint8 pitchAndFamily=DEFAULT_PITCH|FF_DONTCARE,

      uint8 italic=false, uint8 underline=false,

      uint8 strikeout=false,

      uint8 charSet=1,

      uint8 outputPrecision=OUT_DEFAULT_PRECIS,

      uint8 clipPrecision=CLIP_DEFAULT_PRECIS,

      uint8 quality=DEFAULT_QUALITY);

TFont(int height, int width, int escapement=0,

      int orientation=0,

      int weight=FW_NORMAL,

      uint8 italic=false, uint8 underline=false,

      uint8 strikeout=false,

      uint8 charSet=1,

      uint8 outputPrecision=OUT_DEFAULT_PRECIS,

      uint8 clipPrecision=CLIP_DEFAULT_PRECIS,

      uint8 quality=DEFAULT_QUALITY,

      uint8 pitchAndFamily=DEFAULT_PITCH|FF_DONTCARE,

      const char far* facename=0);

The first constructor lets you conveniently plug in the most commonly used attributes for a font (such as name, height, width, and so on) and let the other attributes (which generally have the same value time after time) take their default values. The second constructor has the parameters in the same order as the CreateFont Windows API call so you can easily cut and paste from existing Windows code.

Indirectly creating a font also creates a new object, but it copies the attributes of the object passed to it into the new font object. Here are the constructors for indirectly creating a font:

TFont(const LOGFONT far* logFont);

TFont(const TFont&);

You can also create a new TFont object from an existing HFONT handle:

TFont(HFONT handle, TAutoDelete autoDelete = NoAutoDelete);

This constructor is used to obtain an ObjectWindows object as an alias to a regular Windows handle received in a message.


See Also

Accessing TFont

TFont Class


Accessing TFont (ObjectWindows)

See Also

You can access TFont through an HFONT or as a LOGFONT structure. To get an HFONT from a TFont object, use the HFONT() operator with the TFont object as the parameter. The HFONT() operator is almost never explicitly invoked:

HFONT GetHFont(TFont& font)

{

  return font;

}

This code automatically invokes the HFONT() conversion operator to cast the TFont object to the correct type.

To convert a TFont object to a LOGFONT structure, use the GetObject function:

bool GetLogFont(LOGFONT far& logFont)

{

  TFont font("Times Roman", 20, 8);

  return font.GetObject(logFont);

}


See Also

Constructing TFont

TFont Class


TPalette Class (ObjectWindows)

See Also

The TPalette class encapsulates a Windows color palette that can be used with bitmaps and DIBs. TPalette lets you adjust the color table, match individual colors, move a palette to the Clipboard, and more.

To learn more about TPalette class, review the following topics:

Constructing TPalette

Accessing TPalette

Extending TPalette

TPalette Member Functions


See Also

Changes To Encapsulated GDI Functions

GDI Class Organization

Graphics Objects Overview

TBitmap Class

TBrush Class

TCursor Class

TDib Class

TFont Class

TIcon Class

TPen Class

TRegion Class

Working with Device Contexts


Constructing TPalette (ObjectWindows)

See Also

You can construct a TPalette object either directly, passing an array of color values to the constructor, or indirectly, by specifying a TPalette &, a pointer to a LOGPALETTE structure, a pointer to a bitmap header, and so on. Directly constructing a palette creates a new object with the specified attributes. Here is the constructor for directly constructing a palette:

TPalette(const PALETTEENTRY far* entries, int count);

entries is an array of PALETTEENTRY objects. Each PALETTEENTRY object contains a color value specified by three separate values, one each of red, green, and blue, plus a flags variable for the entry. count specifies the number of values contained in the entries array.

Indirectly creating a palette also creates a new object, but it copies the attributes of the object passed to it into the new palette object. Here are the constructors for indirectly creating a palette:

TPalette(const TClipboard&);

TPalette(const TPalette& palette);

TPalette(const LOGPALETTE far* logPalette);

TPalette(const BITMAPINFO far* info, uint flags=0);

TPalette(const BITMAPCOREINFO far* core, uint flags=0);

TPalette(const TDib& dib, uint flags=0);

Each of these constructors copies into the new object the color values contained in the object passed into the constructor. The objects passed to the constructor are not necessarily palettes themselves; many of them are objects that use palettes and contain a palette themselves. In these cases, the TPalette constructor extracts the palette from the object and copies it into the new palette object.

You can also create a new TPalette object from an existing HPALETTE handle, as follows:

TPalette(HPALETTE handle, TAutoDelete autoDelete = NoAutoDelete);

This constructor is used to obtain an ObjectWindows object as an alias to a regular Windows handle received in a message.


See Also

Accessing TPalette

Extending TPalette

TPalette Member Functions

TPalette Class


Accessing TPalette (ObjectWindows)

See Also

You can access TPalette through an HPALETTE or as a LOGPALETTE structure. To get an HPALETTE from a TPalette object, use the HPALETTE() operator with the TPalette object as the parameter. The HPALETTE() operator is almost never explicitly invoked:

HPALETTE GetHPalette(TPalette& palette)

{

  return palette;

}

This code automatically invokes the HPALETTE() conversion operator to cast the TPalette object to the correct type.

The GetObject function for TPalette functions the same way the Windows API call GetObject does when passed a handle to a palette: It places the number of entries in the color table into the uint16 reference passed to it as a parameter. TPalette::GetObject returns true if successful.


See Also

Constructing TPalette

Extending TPalette

TPalette Member Functions

TPalette Class


TPalette Member Functions (ObjectWindows)

See Also

TPalette encapsulates a number of standard API calls for manipulating palettes:

You can match a color with an entry in a palette using the GetNearestPaletteIndex function. This function takes a single parameter (a TColor object) and returns the index number of the closest match in the palette's color table.

GetNumEntries takes no parameters and returns the number of entries in the palette's color table.

You can get the values for a range of entries in the palette's color table using the GetPaletteEntries function. TPalette::GetPaletteEntries functions just like the Windows API call GetPaletteEntries, except that TPalette::GetPaletteEntries omits the HPALETTE parameter.

You can set the values for a range of entries in the palette's color table using the SetPaletteEntries function. TPalette::SetPaletteEntries functions just like the Windows API call SetPaletteEntries, except that TPalette::SetPaletteEntries omits the HPALETTE parameter.

The GetPaletteEntry and SetPaletteEntry functions work much like GetPaletteEntries and SetPaletteEntries, except that they work on a single palette entry at a time. Both functions take two parameters, the index number of a palette entry and a reference to a PALETTEENTRY object. GetPaletteEntry places the color value of the desired palette entry into the PALETTEENTRY object. SetPaletteEntry sets the palette entry indicated by the index to the value of the PALETTEENTRY object.

You can use the ResizePalette function to resize a palette. ResizePalette takes a uint parameter, which specifies the number of entries in the resized palette. ResizePalette functions exactly like the Windows API ResizePalette call.

The AnimatePalette function lets you replace entries in the palette's color table. AnimatePalette takes three parameters, two uints and a pointer to an array of PALETTEENTRY objects. The first uint specifies the first entry in the palette to be replaced. The second uint specifies the number of entries to be replaced. The entries indicated by these two uints are replaced by the values contained in the array of PALETTEENTRYs.

You can also use the UnrealizeObject function for your palette objects. UnrealizeObject matches the palette to the current system palette. UnrealizeObject takes no parameters and functions just like the Windows API call.

You can move a palette to the Clipboard using the ToClipboard function. ToClipboard takes a reference to a TClipboard object as a parameter. Because the ToClipboard function actually removes the object from your application, you should usually use a TPalette constructor to create a temporary object as follows:

TClipboard clipBoard;

TPalette (tmpPalette).ToClipboard(clipBoard);


See Also

Accessing TPalette

Constructing TPalette

Extending TPalette

TPalette Class


Extending TPalette (ObjectWindows)

See Also

TPalette contains two protected-access functions, both called Create. The two functions differ in that one takes BITMAPINFO * as its first parameter and the other takes a BITMAPCOREINFO * as its first parameter. These functions are called from the TPalette constructors that take a BITMAPINFO *, a BITMAPCOREINFO *, or a TDib &. The BITMAPINFO * and BITMAPCOREINFO * constructors call the corresponding Create functions. The TDib & constructor extracts a BITMAPCOREINFO * or a BITMAPINFO * from its TDib object and calls the appropriate Create function.

Both Create functions take a uint for their second parameter. This parameter is equivalent to the peFlags member of the PALETTEENTRY structure and should be passed either as a 0 or with values compatible with peFlags: PC_EXPLICIT, PC_NOCOLLAPSE, and PC_RESERVED. A palette entry must have the PC_RESERVED flag set to use that entry with the AnimatePalette function.

The Create functions create a LOGPALETTE using the color table from the bitmap header passed as its parameter. You can use Create for 2-, 16-, and 256-color bitmaps. It fails for all other types, including 24-bit DIBs. It then uses the LOGPALETTE to create the HPALETTE.


See Also

Accessing TPalette

Constructing TPalette

TPalette Member Functions

TPalette Class


TBitmap Class (ObjectWindows)

See Also

The TBitmap class encapsulates a Windows device-dependent bitmap, providing a number of different constructors, plus member functions to manipulate and access the bitmap.

To learn more about TBitmap, review the following topics:

Constructing TBitmap

Accessing TBitmap

Extending TBitmap

TBitmap Member Functions


See Also

Changes To Encapsulated GDI Functions

GDI Class Organization

Graphics Objects Overview

TBrush Class

TCursor Class

TDib Class

TFont Class

TIcon Class

TPalette Class

TPen Class

TRegion Class

Working with Device Contexts


Constructing TBitmap (ObjectWindows)

See Also

You can construct a TBitmap object either directly or indirectly. Using direct construction, you can specify the bitmap's width, height, and so on. Using indirect construction, you can specify an existing bitmap object, a pointer to a BITMAP structure, a metafile, a TDC device context, and more.

Here is the constructor for directly constructing a bitmap object:

TBitmap(int width, int height, uint8 planes=1,

        uint8 count=1, void* bits=0);

width and height specify the width and height in pixels of the bitmap. planes specifies the number of color planes in the bitmap. count specifies the number of bits per pixel. Either plane or count must be 1. bits is an array containing the bits to be copied into the bitmap. It can be 0, in which case the bitmap is left uninitialized.

You can create bitmap objects from existing bitmaps, either encapsulated in a TBitmap object or contained in a BITMAP structure.

TBitmap(const TBitmap& bitmap);

TBitmap(const BITMAP far* bitmap);

TBitmap provides two constructors you can use to create bitmap objects that are compatible with a given device context. The first constructor follows:

TBitmap(const TDC& Dc, int width, int height,

        bool discardable = false);

It creates an uninitialized bitmap of the size height by width. Specifying true for the discardable parameter makes the bitmap discardable. A bitmap should never be discarded if it is the currently selected object in a device context.

The second constructor follows:

TBitmap(const TDC& Dc, const TDib& dib, uint32 usage);

It creates a bitmap compatible with the device represented by the device context from a DIB. The usage parameter should be CBM_INIT for 16-bit applications. CBM_INIT indicates that the bitmap should be initialized with the bits contained in the DIB object. If you do not specify CBM_INIT, the bitmap is created, but is left empty. CBM_INIT is the default.

32-bit applications can also specify CBM_CREATEDIB in the usage parameter. The CBM_CREATEDIB flag indicates that the color format of the new bitmap should be compatible with the color format contained in the DIB's BITMAPINFO structure. If the CBM_CREATEDIB flag is not specified, the bitmap is assumed to be compatible with the given device context.

You can also create bitmaps from the Windows Clipboard, from a metafile, or from a DIB object. To create a bitmap from the Clipboard, you only need to pass a reference to a TClipboard object to the constructor. The constructor gets the handle of the bitmap in the Clipboard and constructs a bitmap object from the handle, as follows:

TBitmap(const TClipboard& clipboard);

To create a bitmap from a metafile, you need to pass a TMetaFilePict &, a TPalette &, and a TSize &. The constructor initializes a device-compatible bitmap (based on the palette) and plays the metafile into the bitmap:

TBitmap(const TMetaFilePict& metaFile, TPalette& palette, const TSize& size);

To create a bitmap from a device-independent bitmap, you need to pass a TDib & to the constructor. You can also specify an optional palette. The constructor creates a device context and renders the DIB into a device-compatible bitmap:

TBitmap(const TDib& dib, const TPalette* palette = 0);

You can create a bitmap object by loading it from a module. This constructor takes two parameters, first the HINSTANCE of the module containing the bitmap and second the resource ID of the bitmap you want to load, as follows:

TBitmap(HINSTANCE, TResId);

You can also create a new TBitmap object from an existing HBITMAP handle, as follows:

TBitmap(HBITMAP handle, TAutoDelete autoDelete = NoAutoDelete);

This constructor is used to obtain an ObjectWindows object as an alias to a regular Windows handle received in a message.


See Also

Accessing TBitmap

Extending TBitmap

TBitmap Member Functions

TBitmap Class


Accessing TBitmap (ObjectWindows)

See Also

You can access TBitmap through an HBITMAP or as a BITMAP structure. To get an HBITMAP from a TBitmap object, use the HBITMAP() operator with the TBitmap object as the parameter. The HBITMAP() operator, listed below, is almost never explicitly invoked:

HBITMAP GetHBitmap(TBitmap &bitmap)

{

  return bitmap;

}

This code automatically invokes the HBITMAP() conversion operator to cast the TBitmap object to the correct type.

To convert a TBitmap object to a BITMAP structure, use the GetObject function:

bool GetBitmap(BITMAP far& dest)

{

  TBitmap bitmap(200, 100);

  return bitmap.GetObject(dest);

}

The GetObject function fills out only the width, height, and color format information of the BITMAP structure. You can get the actual bitmap bits with the GetBitmapBits function.


See Also

Constructing TBitmap

Extending TBitmap

TBitmap Member Functions

TBitmap Class


TBitmap Member Functions (ObjectWindows)

SeeAlso

TBitmap also encapsulates a number of standard API calls for manipulating palettes.

You can get the same information as you get from GetObject, except one item at a time, using the following functions. Each function returns a characteristic of the bitmap object:

uint8 Planes();

int Width();

uint8 BitsPixel();

int Height();

The GetBitmapDimension and SetBitmapDimension functions let you find out and change the dimensions of the bitmap. GetBitmapDimension, which takes a reference to a TSize object as its only parameter, places the size of the bitmap into the TSize object. SetBitmapDimension can take two parameters, the first a reference to a TSize object containing the new size for the bitmap, and the second a pointer to a TSize, in which the function places the old size of the bitmap. You do not have to pass the second parameter to SetBitmapDimension. Both functions return true if the operation was successful.

GetBitmapDimension and SetBitmapDimension do not actually affect the size of the bitmap in pixels. Instead they modify only the physical size of the bitmap, which is often used by programs when printing or displaying bitmaps. Using these functions lets you adjust the size of the bitmap depending on the size of the physical screen.

The GetBitmapBits and SetBitmapBits functions let you query and change the bits in a bitmap. Both functions take two parameters: a uint32 and a void *. The uint32 specifies the size of the array in bytes, and the void * points to an array. GetBitmapBits fills the array with bits from the bitmap, up to the number of bytes specified by the uint32 parameter. SetBitmapBits copies the array into the bitmap, copying over the number of bytes specified in the uint32 parameter.

You can move a bitmap to the Clipboard using the ToClipboard function. ToClipboard takes a reference to a TClipboard object as a parameter. Because ToClipboard actually removes the object from your application, you should usually use a TBitmap constructor to create a temporary object, as follows:

TClipboard clipBoard;

TBitmap (tmpBitmap).ToClipboard(clipBoard);


See Also

Accessing TBitmap

Constructing TBitmap

Extending TBitmap


Extending TBitmap (ObjectWindows)

See Also

TBitmap has three functions that have protected access: a constructor and two functions called Create.

The constructor is a default constructor. You can use it when constructing a derived class to prevent having to explicitly call the base class constructor. If you use the default constructor, you need to initialize the bitmap properly in your own constructor.

The first Create function takes a reference to a TBitmap object as a parameter. Essentially, this function copies the passed TBitmap object over to itself.

The second Create function takes references to a TDib object and to a TPalette object. Create creates a device context compatible with the TPalette and renders the DIB into a device-compatible bitmap.


See Also

Accessing TBitmap

Constructing TBitmap


TRegion Class (ObjectWindows)

See Also

Use the TRegion class to define a region in a device context. You can perform a number of operations on a device context, such as painting, filling, inverting, and so on, using the region as a stencil. You can also use the TRegion class to define a region for your own custom operations.

To learn more about TRegion, review the following topics:

Constructing and Destroying TRegion

Accessing TRegion

TRegion Member Functions

TRegion Operators


See Also

Changes To Encapsulated GDI Functions

GDI Class Organization

Graphics Objects Overview

TBitmap Class

TBrush Class

TCursor Class

TDib Class

TFont Class

TIcon Class

TPalette Class

TPen Class

Working with Device Contexts


Constructing and Destructing TRegion (ObjectWindows)
Constructing and Destroying TRegion (ObjectWindows)

See Also

Regions come in many shapes and sizes, from simple rectangles and rectangles with rounded corners to elaborate polygonal shapes. You can determine the shape of your region by using a particular constructor. You can also indirectly construct a region from a handle to a region or from an existing TRegion object.

TRegion provides a default constructor that produces an empty rectangular region. You can use the function SetRectRgn to initialize an empty TRegion object. For example, suppose you derive a class from TRegion. In the constructor for your derived class, call SetRectRgn to initialize the region. This prevents you from having to call TRegion's constructor explicitly:

class TMyRegion : public TRegion

{

public:

  TMyRegion(TRect& rect);

  .

  .

  .

};

TMyRegion::TMyRegion(TRect& rect)

{

  // Initialize the TRegion base with rect.

  SetRectRgn(rect);

}

You can directly create a TRegion from a number of different sources. To create a simple rectangular region, use the following constructor:

TRegion(const TRect& rect);

This constructor creates a rectangular region from the logical coordinates in the TRect object.

To create a rectangular region with rounded corners, use the following constructor:

TRegion(const TRect& rect, const TSize& corner);

This constructor creates a rectangular region from the logical coordinates in the TRect object, then rounds the corners into an ellipse. The height and width of the ellipse used is defined by the values in the TSize object.

To create an elliptical region, use the following constructor:

TRegion(const TRect& e, TEllipse);

This constructor creates an elliptical region bounded by the logical coordinates contained in the TRect structure. TEllipse is an enumerated value with only one possible value, Ellipse. A call to this constructor looks something like this:

TRect rect(20, 20, 80, 60);

TRegion rgn(rect, TRegion::Ellipse);

To create regions with an irregular polygonal shape, use the following constructor:

TRegion(const TPoint* points, int count, int fillMode);

points is an array of TPoint objects. Each TPoint contains the logical coordinates of a vertex of the polygon. count indicates the number of points in the points array. fillMode indicates how the region should be filled, either ALTERNATE or WINDING.

There is another constructor that you can use to create regions consisting of multiple irregular polygonal shapes:

TRegion(const TPoint* points, const int* polyCounts,

        int count, int fillMode);

As in the other polygonal region constructor, points is an array of TPoint objects. But for this constructor, points contains the vertex points of a number of polygons. polyCounts indicates the number of points in the points array for each polygon. count indicates the total number of polygons in the region and the number of members in the polyCount array. fillMode indicates how the region should be filled, either ALTERNATE or WINDING.

For example, suppose you are constructing a region that encompasses two triangular areas. Each triangle would consist of three points. Therefore points would have six members, three for each triangle. polyPoints would have two members, one for each triangle. Each member of polyPoints would have the value 3, indicating the number of points in the points array that belongs to each polygon. count would have the value 2, indicating that the region consists of two polygons.

You can create a TRegion from an existing HRGN, as follows:

TRegion(HRGN handle, TAutoDelete autoDelete = NoAutoDelete);

This constructor is used to obtain an ObjectWindows object as an alias to a regular Windows handle received in a message.

You can also create a new TRegion object from an existing TRegion object:

TRegion(const TRegion& region);

The destructor ~TRegion deletes the region and its storage space.


See Also

Accessing TRegion

TRegion Member Functions

TRegion Operators


Accessing TRegion (ObjectWindows)

See Also

You can access and modify TRegion objects directly through an HRGN handle or through a number of member functions and operators. To get an HRGN from a TRegion object, use the HRGN() operator with the TRegion object as the parameter. The HRGN() operator is almost never explicitly invoked:

HRGN TMyBitmap::GetHRgn()

{

  return *this;

}

This code automatically invokes the HRGN() conversion operator to cast the TRegion object to the correct type.


See Also

Constructing and Destroying TRegion

TRegion Member Functions

TRegion Operators


TRegion Member Functions (ObjectWindows)

See Also

TRegion provides a number of member functions to get information from the TRegion object, including whether a point is contained in or touches the region.

You can use the SetRectRgn function to reset the object's region to a rectangular region:

void SetRectRgn(const TRect& rect);

This function sets the TRegion's area to the logical coordinates contained in the TRect object passed as a parameter to SetRectRgn. The region is set to a rectangular region regardless of the shape that it previously had.

You can use the Contains function to find out whether a point is contained in a region:

bool Contains(const TPoint& point);

point contains the coordinates of the point in question. Contains returns true if point is within the region and false if not.

You can use the Touches function to find out whether any part of a rectangle is contained in a region:

bool Touches(const TRect& rect);

rect contains the coordinates of the rectangle in question. Touches returns true if any part of rect is within the region and false if not.

You can use the GetRgnBox functions to get the coordinates of the bounding rectangle of a region:

int GetRgnBox(TRect& box);

TRect GetRgnBox();

The bounding rectangle is the smallest possible rectangle that encloses all the area contained in the region. The first version of this function takes a reference to a TRect object as a parameter. The function places the coordinates of the bounding rectangle in the TRect object. The return value indicates the complexity of the region, and can be one of the following: SIMPLEREGION (region has no overlapping borders), COMPLEXREGION (region has overlapping borders), or NULLREGION (region is empty). If the function fails, the return value is ERROR.

The second version of GetRgnBox takes no parameters and returns a TRect that contains the coordinates of the bounding rectangle. The second version of this function does not indicate the complexity of the region.


See Also

Accessing TRegion

Constructing and Destroying TRegion

TRegion Operators


TRegion Operators (ObjectWindows)

See Also

TRegion has a large number of operators. These operators can be used to query and modify the values of a region. They are not necessarily restricted to working with other regions; many of them let you add and subtract rectangles and other units to and from the region.

TRegion provides two Boolean test operators, == and !=. These operators work to compare two regions. If two regions are equivalent, the == operator returns true, and the != operator returns false. If two regions are not equivalent, the == operator returns false, and the != operator returns true. You can use these operators much as you do their equivalents for ints, chars, and so on.

For example, suppose you want to test whether two regions are identical, and, if they are not, perform an operation on them. The code would look something like this:

TRegion rgn1;

TRegion rgn2;

// Initialize regions...

if(rgn1 != rgn2) {

  // Perform your operations here

  .

  .

  .

}

TRegion also provides a number of assignment operators that you can use to change the region:

The = operator lets you assign one region to another. For example, the statement rgn1 = rgn2 sets the contents of rgn1 to the contents of rgn2, regardless of the contexts of rgn1 prior to the assignment.

The += operator lets you move a region by an offset contained in a TSize object. This operation is analogous to numerical addition: just add the offset to each point in the region. The region retains all its properties, except that the coordinates defining the region are shifted by the values contained in the cx and cy members of the TSize object:

If cx is positive, the region is shifted cx pixels to the right.

If cx is negative, the region is shifted cx pixels to the left.

If cy is positive, the region is shifted cy pixels down.

If cy is negative, the region is shifted cy pixels up.

For example, suppose you want to move a region to the right 50 pixels and up 20 pixels. The code would look something like this:

TRegion rgn;

// Initialize region...

TSize size(50, -20);

rgn += size;

// Continue working with new region.

  .

  .

  .

The -= operator, when used with a TSize object, does essentially the opposite of the += operator; that is, it subtracts the offset from each point in the region. For example, suppose you have the same code as in the previous example, except that instead of using the += operator, it uses the -= operator. This code would offset the region in exactly the opposite way from the += operator, 50 pixels to the left and down 20 pixels.

The -= operator, when used with a TRegion object, behaves differently from when it is used with a TSize object. To demonstrate how the -= operator works when used with TRegion, consider the following code:

TRegion rgn1, rgn2;

rgn1 -= rgn2;

After execution of this code, rgn1 contains all the area it contained originally, minus any parts of that area shared by rgn2. Thus any point that is contained in rgn2 is not contained in rgn1 after this code has executed. This is analogous to subtraction: subtract the area defined by rgn2 from rgn1.

The &= operator can be used with both TRegion objects and TRect objects (before any operations are performed, the TRect is converted to a TRegion using the constructor TRegion::TRegion(TRect &)).  The following code demonstrates how the &= operator works:

TRegion rgn1, rgn2;

rgn1 &= rgn2;

After execution of this code, rgn1 contains all the area it originally shared with rgn2; that is, areas that were common to both regions before the execution of the &= statement. This is a logical AND operation: only the areas that are part of both rgn1 AND rgn2 become part of the new region.

The |= operator can be used with both TRegion objects and TRect objects (before any operations are performed, the TRect is converted to a TRegion using the constructor TRegion::TRegion(TRect &)). The following code demonstrates how the |= operator works:

TRegion rgn1, rgn2;

rgn1 |= rgn2;

After execution of this code, rgn1 contains all the area it originally contained, plus all the area contained in rgn2; that is, it contains all of both regions. This is a logical OR operation: Areas that are part of either rgn1 OR rgn2 become part of the new region.

The ^= operator can be used with both TRegion objects and TRect objects (before any operations are performed, the TRect is converted to a TRegion using the constructor TRegion::TRegion(TRect &)). The following code demonstrates how the ^= operator works:

TRegion rgn1, rgn2;

rgn1 ^= rgn2;

After execution of this code, rgn1 contains only that area it originally contained but did not share with rgn2, plus all the area originally contained in rgn2 that was not shared with rgn1. This operator combines both areas and removes the overlapping sections. This is a logical XOR (exclusive OR) operation: Areas that are part of either rgn1 OR rgn2 but not of both become part of the new region.


See Also

Constructing and Destroying TRegion

Accessing TRegion

TRegion Member Functions


TIcon Class (ObjectWindows)

See Also

The TIcon class encapsulates an icon handle and constructors for instantiating the TIcon object. You can use the TIcon class to construct an icon from a resource or explicit info.

To learn more about TIcon, review the following topics:

Constructing TIcon

Accessing TIcon


See Also

Changes To Encapsulated GDI Functions

GDI Class Organization

Graphics Objects Overview

TBitmap Class

TBrush Class

TCursor Class

TDib Class

TFont Class

TIcon Class

TPalette Class

TPen Class

Working with Device Contexts


Constructing TIcon (ObjectWindows)

See Also

You can construct a TIcon in a number of ways: from an existing TIcon object, from a resource in the current application, from a resource in another module, or explicitly from size and data information.

You can create icon objects from an existing icon encapsulated in a TIcon object:

TIcon(HINSTANCE instance, const TIcon& icon);

instance can be any module instance. For example, you could get the instance of a DLL and get an icon from that instance:

TModule iconLib("MYICONS.DLL");

TIcon icon(iconLib, "MYICON");

Note the implicit conversion of the TModule iconLib into an HINSTANCE in the call to the TIcon constructor.

You can create a TIcon object from an icon resource in any module:

TIcon(HINSTANCE instance, TResId resId);

In this case, instance should be the HINSTANCE of the module from which you want to get the icon, and resId is the resource ID of the particular icon you want to get. Passing in 0 for instance gives you access to built-in Windows icons.

You can also load an icon from a file:

TIcon(HINSTANCE instance, char far* filename, int index);

In this case, instance should be the instance of the current module, filename is the name of the file containing the icon, and index is the index of the icon to be retrieved.

You can also create a new icon:

TIcon(HINSTANCE instance, TSize& size, int planes, int bitsPixel,

      void far* andBits, void far* xorBits);

In this case, instance should be the instance of the current module, size indicates the size of the icon, planes indicates the number of color planes, bitsPixel indicates the number of bits per pixel, andBits points to an array containing the AND mask of the icon, and xorBits points to an array containing the XOR mask of the icon. The andBits array must specify a monochrome mask. The xorBits array can be a monochrome or device-dependent color bitmap.

You can also create a new TIcon object from an existing HICON handle:

TIcon(HICON handle, TAutoDelete autoDelete = NoAutoDelete);

This constructor is used to obtain an ObjectWindows object as an alias to a regular Windows handle received in a message.

There are two other constructors that are available only for 32-bit applications:

TIcon(const void* resBits, uint32 resSize);

TIcon(const ICONINFO* iconInfo);

The first constructor takes two parameters: resBits is a pointer to a buffer containing the icon data bits (usually obtained from a call to LookupIconIdFromDirectory or LoadResource functions) and resSize indicates the number of bits in the resBits buffer.

The second constructor takes a single parameter, an ICONINFO structure. The constructor creates an icon from the information in the ICONINFO structure. The fIcon member of the ICONINFO structure must be true, indicating that the ICONINFO structure contains an icon.

The destructor ~TIcon deletes the icon and its storage space.


See Also

Accessing TIcon


Accessing TIcon (ObjectWindows)

See Also

You can access TIcon through an HICON. To get an HICON from a TIcon object, use the HICON() operator with the TIcon object as the parameter. The HICON() operator is almost never explicitly invoked:

HICON TMyIcon::GetHIcon()

{

  return *this;

}

This code automatically invokes the HICON() conversion operator to cast the TIcon object to the correct type.

The other access function in TIcon, called GetIconInfo, is available for 32-bit applications only. GetIconInfo takes as its only parameter a pointer to a ICONINFO structure. The function fills out the ICONINFO structure and returns true if the operation was successful. For example, suppose you create an icon object, then want to extract the icon data into an ICONINFO structure. The code would look something like this:

ICONINFO iconInfo;

// Load stock icon - Exclamation

TIcon icon(0, IDI_EXCLAMATION);

icon.GetIconInfo(&iconInfo);


See Also

Constructing TIcon


TCursor Class (ObjectWindows)

See Also

The TCursor class encapsulates a cursor handle and constructors for instantiating the TCursor object. You can use the TCursor class to construct a cursor from a resource or explicit information.

To learn more about TCursor, review the following topics:

Constructing TCursor

Accessing TCursor


See Also

Changes To Encapsulated GDI Functions

GDI Class Organization

Graphics Objects Overview

TBitmap Class

TBrush Class

TDib Class

TFont Class

TIcon Class

TPalette Class

TPen Class

TRegion Class

Working with Device Contexts


Constructing TCursor (ObjectWindows)

See Also

You can construct a TCursor in a number of ways: from an existing TCursor object, from a resource in the current application, from a resource in another application, or explicitly from size and data information.

You can create cursor objects from an existing cursor encapsulated in a TCursor object:

TCursor(HINSTANCE instance, const TCursor& cursor);

instance in this case should be the instance of the current application. TCursor does not encapsulate the application instance because TCursor objects know nothing about application objects. It is usually easiest to access the current application instance in a window or other interface object.

TCursor(HINSTANCE instance, TResId resId);

TCursor(HINSTANCE instance, const TPoint& hotSpot,

        TSize& size, void far* andBits, void far* xorBits);

You can also create a new TCursor object from an existing HCURSOR handle:

TCursor(HCURSOR handle, TAutoDelete autoDelete = NoAutoDelete);

This constructor is used to obtain an ObjectWindows object as an alias to a regular Windows handle received in a message.

There are two other constructors that are available only for 32-bit applications:

TCursor(const void* resBits, uint32 resSize);

TCursor(const ICONINFO* iconInfo);

The first constructor takes two parameters: resBits is a pointer to a buffer containing the cursor data bits (usually obtained from a call to LookupIconIdFromDirectory or LoadResource functions) and resSize indicates the number of bits in the resBits buffer.

The second constructor takes a single parameter, an ICONINFO structure. The constructor creates an icon from the information in the ICONINFO structure. The fIcon member of the ICONINFO structure must be false, indicating that the ICONINFO structure contains a cursor.

The destructor ~TCursor deletes the cursor. If the deletion fails, the destructor throws an exception.


See Also

Accessing TCursor


Accessing TCursor (ObjectWindows)

See Also

You can access TCursor through an HCURSOR. To get an HCURSOR from a TCursor object, use the HCURSOR() operator with the TCursor object as the parameter. The HCURSOR() operator, listed below, is almost never explicitly invoked:

HCURSOR

TMyCursor::GetHCursor()

{

  return *this;

}

This code automatically invokes the HCURSOR() conversion operator to cast the TCursor object to the correct type.

The other access function in TCursor, called GetIconInfo, is available for 32-bit applications only. GetIconInfo takes as its only parameter a pointer to a ICONINFO structure. The function fills out the ICONINFO structure and returns true if the operation was successful. For example, suppose you create an cursor object, then want to extract the cursor data into an ICONINFO structure. The code would look something like this:

ICONINFO cursorInfo;

// Load stock cursor - slashed circle

TCursor cursor(NULL, IDC_NO);

cursor.GetIconInfo(&cursorInfo);


See Also

Constructing TCursor


TDib Class (ObjectWindows)

See Also

A device-independent bitmap (DIB) has no GDI handle like a regular bitmap, although it does have a global handle. Instead, it is just a structure containing format and palette information and a collection of bits (pixels). The TDib class provides a convenient way to work with DIBs like any other GDI object. The memory for the DIB is in one chunk allocated with the Windows GlobalAlloc functions, so that it can be passed to the Clipboard, an OLE server or client, and others outside of its instantiating application.

To learn more about TDib, review the following topics:

Constructing and Destroying TDib

Accessing TDib

Accessing Internal Structures

Extending TDib


See Also

Changes To Encapsulated GDI Functions

GDI Class Organization

Graphics Objects Overview

TBitmap Class

TBrush Class

TCursor Class

TFont Class

TIcon Class

TPalette Class

TPen Class

TRegion Class

Working with Device Contexts


Constructing and Destructing TDib (ObjectWindows)
Constructing and Destroying TDib (ObjectWindows)

See Also

You can construct a TDib object either directly or indirectly. Using direct construction, you can specify the bitmap's width, height, and so on. Using indirect construction, you can specify an existing bitmap object, pointer to a BITMAP structure, a metafile, a TDC device context, and more.

Here is the constructor for directly constructing a TDib object:

TDib(int width, int height, int nColors, uint16 mode=DIB_RGB_COLORS);

width and height specify the width and height in pixels of the DIB. nColors specifies the number of colors actually used in the DIB. mode can be either DIB_RGB_COLORS or DIB_PAL_COLORS. DIB_RGB_COLORS indicates that the color table consists of literal RGB values. DIB_PAL_COLORS indicates that the color table consists of an array of 16-bit indexes into the currently realized logical palette.

You can create a TDib object by loading it from an executable application module. This constructor takes two parameters: the first is the HINSTANCE of the module containing the bitmap and the second is the resource ID of the bitmap you want to load:

TDib(HINSTANCE instance, TResId resId);

To create a TDib object from the Clipboard, pass a reference to a TClipboard object to the constructor. The constructor gets the handle of the bitmap in the Clipboard and constructs a bitmap object from the handle.

TDib(const TClipboard& clipboard);

You can load a DIB from a file (typically a .BMP file) into a TDib object by specifying the name as the only parameter of the constructor:

TDib(const char* name);

You can also construct a TDib object given a TBitmap object and a TPalette object. If no palette is given, this constructor uses the focus window's currently realized palette.

TDib(const TBitmap& bitmap, const TPalette* pal = 0);

You can create a DIB object from an existing DIB object:

TDib(const TDib& dib);

You can also create a new TDib object from an existing HGLOBAL handle:

TDib(HGLOBAL handle, TAutoDelete autoDelete = NoAutoDelete);

This constructor is used to obtain an ObjectWindows object as an alias to a regular Windows handle received in a message. Because an HGLOBAL handle can point to many different kinds of objects, you must ensure that the HGLOBAL you use in this constructor is actually the handle to a device-independent bitmap. If you pass a handle to another type of object, the constructor throws an exception.

If ShouldDelete is true, the destructor ~TDib frees the resource and unlocks and frees the chunk of global memory as needed.


See Also

Accessing TDib

Extending TDib


Accessing TDib (ObjectWindows)

See Also

TDib provides a number of different types of functions for accessing the encapsulated DIB.

To find out more about accessing the encapsulated DIB, review the following topics:

Type Conversions

Accessing Internal Structures

Clipboard

DIB Information

Working in PAL Or RGB Mode

Matching Interface Colors To System Colors


See Also

Constructing and Destroying TDib

Extending TDib


Type Conversions (ObjectWindows)

See Also

The type conversion functions for TDib let you access TDib in the most convenient manner for the operation you want to perform.

You can use the HANDLE conversion operator to access TDib through a HANDLE. To get a HANDLE from a TDib object, use the HANDLE operator with the TDib object as the parameter. The HANDLE operator is almost never explicitly invoked:

HANDLE TMyDib::GetHandle()

{

  return *this;

}

This code automatically invokes the HANDLE conversion operator to cast the TDib object to the correct type.

You can also convert a TDib object to three other bitmap types. You can use the following operators to convert a TDib to any one of three types: BITMAPINFO *, BITMAPINFOHEADER *, or TRgbQuad *. You can use the result wherever that type is normally used:

operator BITMAPINFO far*();

operator BITMAPINFOHEADER far*();

operator TRgbQuad far*();


See Also

Accessing Internal Structures

Clipboard

DIB Information

Matching Interface Colors To System Colors

Working in PAL Or RGB Mode


Accessing Internal Structures (ObjectWindows)

See Also

These TDib functions give you access to a device-independent bitmap's (DIB's) internal data structures. They return the DIB's equivalent bitmap types as pointers to BITMAPINFO, BITMAPINFOHEADER, and TRgbQuad objects:

BITMAPINFO far* GetInfo();

BITMAPINFOHEADER far* GetInfoHeader();

TRgbQuad far* GetColors();

The following function returns a pointer to an array of WORDs containing the color indexes for the DIB:

uint16 far* GetIndices();

This function returns a pointer to an array containing the bits that make up the actual DIB image:

void HUGE* GetBits();


See Also

Clipboard

DIB Information

Matching Interface Colors To System Colors

Type Conversions

Working in PAL Or RGB Mode


Clipboard (ObjectWindows)

See Also

You can move a DIB to the Clipboard using the ToClipboard function, which takes a reference to a TClipboard object as a parameter. Because ToClipboard actually removes the object from your application, you should usually use a TDib constructor to create a temporary object, as follows:

TClipboard clipBoard;

TDib(ID_BITMAP).ToClipboard(clipBoard);


See Also

Accessing Internal Structures

DIB Information

Matching Interface Colors To System Colors

Type Conversions

Working in PAL Or RGB Mode


DIB Information (ObjectWindows)

See Also

The TDib class provides a number of accessor functions that you can use to query a TDib object and get information about the DIB contained in the object:

To find out whether the object is valid, call the IsOK function. IsOK takes no parameters. It returns true if the object is valid and false if not.

The IsPM function takes no parameters. This function returns true when the DIB is a Presentation Manager-compatible bitmap.

The Width and Height functions return the bitmap's width and height respectively, in pixel units.

The Size function returns the bitmap's width and height in pixel units, but contained in a TSize object.

The NumColors function returns the number of colors used in the bitmap.

StartScan is provided for compatibility with older code. This function always returns 0.

NumScans is provided for compatibility with older code. This functions returns the height of the DIB in pixels.

The Usage function indicates what mode the DIB is in. This value is either DIB_RGB_COLORS or DIB_PAL_COLORS.

The WriteFile function writes the DIB object to disk. This function takes a single parameter, a const char*, which should point to the name of the file in which you want to save the bitmap.


See Also

Accessing Internal Structures

Clipboard

Matching Interface Colors To System Colors

Type Conversions

Working in PAL Or RGB Mode


Working in PAL Or RGB Mode (ObjectWindows)

See Also

A device-independent bitmap (DIB) can hold color values in two ways. In palette mode, the DIB's color table contains indexes into a palette. The color values do not indicate any particular color themselves. The indexes must be cross-referenced to the corresponding palette entry in the currently realized palette. In RGB mode, each entry in the DIB's color table represents an actual RGB color value.

You can switch from RGB to palette mode by using these TDib functions:

bool ChangeModeToPal(const TPalette& pal);

bool ChangeModeToRGB(const TPalette& pal);

When you switch to palette mode using ChangeModetoPal, the TPalette & parameter is used as the DIB's palette. Each color used in the DIB is mapped to the palette and converted to a palette index. When you switch to RGB mode using ChangeModetoRGB, the TPalette & parameter is used to convert the current palette indexes to their RGB equivalents contained in the palette.

Working In Rgb Mode

If you're working in RGB mode, you can use the following functions to access and modify the DIB's color table:

Retrieve any entry in the DIB's color table using the GetColor function. This function takes a single parameter, an int indicating the index of the color table entry. GetColor returns a TColor object.

Change any entry in the DIB's color table using the SetColor function. This function takes two parameters, an int indicating the index of the color table entry you want to change and a TColor containing the value to which you want to change the entry.

Match a TColor object to a color table entry by using the FindColor function. FindColor takes a single parameter, a TColor object, and searches through the DIB's color table until it finds an exact match for the TColor object. If it fails to find a match, FindColor returns -1.

Substitute one color for a color that currently exists in the DIB's color table using the MapColor function. This function takes three parameters, a TColor object containing the color to be replaced, a TColor object containing the new color to be placed in the color table, and a bool that indicates whether all occurrences of the second color should be replaced. If the third parameter is true, all color table entries that are equal to the first parameter are replaced by the second. If the third parameter is false, only the first color table entry that is equal to the first parameter is replaced. By default, the third parameter is false. The return value of this function indicates the total number of palette entries that were replaced.

For example, suppose you wanted to replace all occurrences of white in your DIB with light gray. The code would look something like this:

myDib->MapColor(TColor::LtGray, TColor::White, true);

Working In Palette Mode

If you're working in palette mode, you can use the following functions to access and modify the DIB's color table:

Retrieve the palette index of any color table entry using the GetIndex   function. This function takes a single parameter, an int indicating the index of the color table entry. GetIndex returns a uint16 containing the palette index.

Change any entry in the DIB's color table using the SetIndex function. This function takes two parameters, an int indicating the index of the color table entry you want to change and a uint16 containing the palette index to which you want to change the entry.

Match a palette index to a color table entry by using the FindIndex function. FindIndex takes a single parameter, a uint16 and searches through the DIB's color table until it finds a match for the uint16. If it fails to find a match, FindIndex returns -1.

Substitute one color for a color that currently exists in the DIB's color table using the MapIndex function. This function takes three parameters, a uint16 indicating the index to be replaced, a uint16 indicating the new palette index to be placed in the color table, and a bool that indicates whether all occurrences of the second color should be replaced. If the third parameter is true, all color table entries that are equal to the first parameter are replaced by the second. If the third parameter is false, only the first color table entry that is equal to the first parameter is replaced. By default, the third parameter is false. The return value of this function indicates the total number of palette entries that were replaced.


See Also

Accessing Internal Structures

Clipboard

DIB Information

Matching Interface Colors To System Colors

Type Conversions


Matching Interface Colors To System Colors (ObjectWindows)

See Also

Device-independent bitmaps (DIBs) are often used to enhance and decorate a user interface. To make your interface consistent with your application user's system, you should use TDib's MapUIColors function, which replaces standard interface colors with the user's own system colors. Here is the syntax for MapUIColors:

void MapUIColors(uint mapColors, TColor* bkColor = 0);

The mapColors parameter should be an OR'ed combination of five flags: TDib::MapFace, TDib::MapText, TDib::MapShadow, TDib::MapHighlight, and TDib::MapFrame. Each of these values causes a different color substitution to take place, as shown in the following table:

This flag	Replaces...	With...

TDib::MapText	TColor::Black	COLOR_BTNTEXT

TDib::MapFace	TColor::LtGray	COLOR_BTNFACE

TDib::MapFace	TColor::Gray	COLOR_BTNSHADOW

TDib::MapFace	TColor::White	COLOR_BTNHIGHLIGHT

TDib::MapFrame	TColor::LtMagenta	COLOR_WINDOWFRAME

The bkColor parameter, if specified, causes the color TColor::LtYellow to be replaced by the color bkColor.

Because MapUIColors searches for and replaces TColor table entries, this function is useful only with a DIB in RGB mode. Furthermore, because it replaces particular colors, you must design your interface using the standard system colors. For example, your button text should be black (TColor::Black), button faces should be light gray (TColor::LtGray), and so on. This should be fairly simple, since these objects are specifically designed so that they are equivalent to the standard default colors for each interface element.

You should also call the MapUIColors function before you modify any of the colors modified by MapUIColors. If you do not do this, MapUIColors will not be able to find the attribute color for which it is searching, and that part of the interface will not match the system colors.


See Also

Accessing Internal Structures

Clipboard

DIB Information

Type Conversions

Working in PAL Or RGB Mode


Extending TDib (ObjectWindows)

See Also

TDib provides a number of protected functions that are accessible only from within TDib and TDib-derived classes. You can also access TDib's control data, described in the following table:

Data item	Description

Info	A pointer to a BITMAPINFO or BITMAPCOREINFO structure that contains the attributes, color table, and other information about the DIB

Bits	A void pointer that points to an area of memory containing the actual graphical data for the DIB

NumClrs	A long containing the actual number of colors used in the DIB (not the number of colors possible, but the number actually used)

W	An int indicating the width of the DIB in pixels

H	An int indicating the height of the DIB in pixels

Mode	A uint16 indicating whether the DIB is in RGB mode (DIB_RGB_COLORS) or palette mode (DIB_PAL_COLORS)

IsCore	A bool that is true if the Info pointer points to a BITMAPCOREINFO structure and false if it does not

IsResHandle	Indicates whether the DIB was loaded as a resource and therefore whether Handle is a resource handle

You can use the InfoFromHandle function to fill out the structure pointed to by Info. InfoFromHandle extracts information from Handle and fills out the attributes of the Info structure. InfoFromHandle takes no parameters and has no return value.

The Read function reads a Windows 3.0-compatible or Presentation Manager-compatible DIB from a file referenced by a TFile object. When loading, Read checks the DIB's header, attributes, palette, and bitmap. Presentation Manager-compatible DIBs are converted to Windows DIBs on the fly. This function returns true if the DIB was read in correctly.

You can use the LoadResource function to load a DIB from an application or DLL module. This function takes two parameters, an HINSTANCE indicating the application or DLL module from which you want to load the DIB and a TResId indicating the particular resource within that module you want to retrieve. LoadResource returns true if the operation was successful.

You can use the LoadFile function to load a DIB from a file. This function takes one parameter, a char * that points to a string containing the name of the file containing the DIB. LoadFile returns true if the operation was successful.


See Also

Accessing TDib

Constructing and Destroying TDib


Validator Objects Overview (ObjectWindows)

ObjectWindows provides several ways you can associate validator objects with the edit control objects to validate the information a user types into an edit control. Using validator objects makes it easy to add data validation to existing ObjectWindows applications or to change the way a field validates its data.

These three tasks are related to data validation:

Using the standard validator classes

Using data validator objects

Overriding validator member functions

At any time, you can validate the contents of any edit control or data screen by calling that object's CanClose method, which in turn calls the appropriate validator object. ObjectWindows validator classes also interact at the keystroke and the gain/lose focus level.


The Standard Validator Classes (ObjectWindows)

See Also

The ObjectWindows standard validator classes automate data validation.

ObjectWindows defines six validator classes in validate.h:

Class type	Class Name	Description

Validator base class	TValidator	A base class from which all other validator classes are derived

Filter validator class	TFilterValidator	A filter validator class

Range validator class	TRangeValidator	A numeric-range validator class based on TFilterValidator

Lookup validator class	TLookupValidator	A lookup validator base class

String lookup validator class	TStringLookupValidator	A string lookup validator class based on TLookupValidator

Picture validator class	TPXPictureValidator	A picture validator class that validates a string based on a given pattern or "picture"


See Also

Validator Objects


Validator Base Class (ObjectWindows)

See Also

The abstract class TValidator is the base class from which all validator classes are derived. TValidator is a validator for which all input is valid: Member functions IsValid and IsValidInput always return true, and Error does nothing. Derived classes should override IsValid, IsValidInput, and Error to define which values are valid and when errors should be reported. Use TValidator as a starting point for your own validator classes if none of the other validator classes are appropriate starting points.


See Also

Filter Validator Class

Range Validator Class

Lookup Validator Class

String Lookup Validator Class

Picture Validator Class


Filter Validator Class (ObjectWindows)

See Also

TFilterValidator is a simple validator that checks input as the user enters it. The filter validator constructor takes one parameter, a set of valid characters:

TFilterValidator(const TCharSet& validChars);

TCharSet is defined in bitset.h.

TFilterValidator overrides IsValidInput to return true only if all characters in the current input string are contained in the set of characters passed to the constructor.

The edit control inserts characters only if IsValidInput returns true, so there is no need to override IsValid. Because the characters made it through the input filter, the complete string is valid by definition.

Descendants of TFilterValidator, such as TRangeValidator, can combine filtering of input with other checks on the completed string.


See Also

Validator Base Class

Range Validator Class

Lookup Validator Class

String Lookup Validator Class

Picture Validator Class


Range Validator Class (ObjectWindows)

See Also

TRangeValidator is a range validator derived from TFilterValidator. It accepts only numbers and adds range checking on the final result.

The constructor takes two parameters that define the minimum and maximum valid values:

TRangeValidator(long min, long max);

The range validator constructs itself as a filter validator that accepts only the digits 0 through 9 and the plus (+) and minus (-) characters. The inherited IsValidInput, therefore, ensures that only numbers filter through. TRangeValidator then overrides IsValid to return true only if the entered numbers are a valid integer within the range defined in the constructor. The Error method displays a message box indicating that the entered value is out of range.


See Also

Validator Base Class

Filter Validator Class

Lookup Validator Class

String Lookup Validator Class

Picture Validator Class


Lookup Validator Class (ObjectWindows)

See Also

TLookupValidator is an abstract class that compares entered values with a list of acceptable values to determine validity. TLookupValidator introduces the virtual member function Lookup. By default, Lookup returns true. Derived classes should override Lookup to compare the parameter with a list of items, returning true if a match is found.

TLookupValidator overrides IsValid to return true only if Lookup returns true. In derived classes you should not override IsValid; you should instead override Lookup. TStringLookupValidator class is an instance class based on TLookupValidator.


See Also

Validator Base Class

Filter Validator Class

Range Validator Class

String Lookup Validator Class

Picture Validator Class


String Lookup Validator Class (ObjectWindows)

See Also

TStringLookupValidator is a working example of a lookup validator; it compares the string passed from the edit control with the items in a string list. If the passed-in string occurs in the list, IsValid returns true.

The constructor takes only one parameter, a pointer to a TSortedStringArray object containing the list of valid strings:

TStringLookupValidator(TSortedStringArray* strings);

Using a different string list

To use a different string list after constructing the string lookup validator, use member function NewStringList, which disposes of the old list and installs the new list.

TStringLookupValidator overrides Lookup and Error. Lookup returns true if the passed-in string is in the list. Error displays a message box indicating that the string is not in the list.


See Also

Validator Base Class

Filter Validator Class

Range Validator Class

Lookup Validator Class

Picture Validator Class


Picture Validator Class (ObjectWindows)

See Also

Picture validators compare the string entered by the user with a "picture" or template that describes the format of valid input. The pictures used are compatible with those used by Borland's Paradox relational database to control user input.

Constructing a picture validator requires two parameters: a string holding the template image and a Boolean value indicating whether to automatically fill-in the picture with literal characters:

TPXPictureValidator(const char far* pic, bool autoFill=false);

TPXPictureValidator overrides Error, IsValid, and IsValidInput, and adds a new member function, Picture. Error displays a message box indicating what format the string should have. IsValid returns true only if the function Picture returns true; thus you can derive new kinds of picture validators by overriding only the Picture member function. IsValidInput checks characters as the user enters them, allowing only those characters permitted by the picture format and optionally filling in literal characters from the picture format.

Example

Here is an example of a picture validator that is being constructed to accept social security numbers:

edit->SetValidator(new TPXPictureValidator("###-##-####"));

The Picture member function tries to format the given input string according to the picture format and returns a value indicating the degree of its success.

The following code lists those return values:

//

// TPXPictureValidator result type

//

enum TPicResult {

  prComplete,

  prIncomplete,

  prEmpty,

  prError,

  prSyntax,

  prAmbiguous,

  prIncompNoFill

};


See Also

Validator Base Class

Filter Validator Class

Range Validator Class

Lookup Validator Class

String Lookup Validator Class


Using Data Validators (ObjectWindows)

To use data validator objects, you must:

1.	Construct an edit control object

2.	Construct a validator object

3.	Assign it to the edit control

From that point on, you do not need to interact with the validator object directly. The edit control knows when to call validator methods at the appropriate times.


Constructing an Edit Control Object (ObjectWindows)

See Also

Edit-control objects are instances of the TEdit class.

Here is an example of how to construct an edit control:

TEdit* edit;

edit = new TEdit(this, 101, sizeof(transfer.NameEdit));


See Also

Constructing and Assigning a Validator Object


Constructing and Assigning Validator Objects (ObjectWindows)

See Also

Establishing the validation criteria

Because validator objects are not interface objects, their constructors require only enough information to establish the validation criteria. For example, a numeric-range validator object requires only two parameters: the minimum and maximum values in the valid range.

Every edit control object has a data member that can point to a validator object. This pointer's declaration looks like this:

TValidator *Validator

Assigning Validator Objects

Assign a validator by calling the edit control object's SetValidator member function. The edit control automatically checks with the validator object when processing key events and when called on to validate itself.

Examples

The following code shows the construction of a validator and its assignment to an edit control. In this case, a filter validator that allows only alphabetic characters is used.

edit->SetValidator(new TFilterValidator("A-Za-z. "));

A complete example showing the use of the standard validators can be found in \BORLANDC\EXAMPLES\OWL\OWLAPI\VALIDATE.


See Also

Constructing an Edit Control Object

TFilterValidator

TValidator


Overriding Validator Member Functions (ObjectWindows)

Although the standard validator objects should satisfy most of your data validation needs, you can also modify the standard validators or write your own validation objects. If you decide to do this, you should be familiar with the following list of member functions inherited from the base class TValidator.

Valid

IsValid

IsValidInput

Error

In addition to understanding what each member function does, you should also know how edit controls use them and how to override them if necessary.


Member Function Valid (ObjectWindows)

See Also

Member function Valid is called by the associated edit-control object to verify that the data entered is valid. Much like the CanClose methods of interface objects, Valid is a Boolean function that returns true only if the string passed to it is valid data. One responsibility of an edit control's CanClose method is to call the validator object's Valid method, passing the edit control's current text.

When using validators with edit controls, you usually do not need to call or override the validator's Valid method; the inherited version of Valid will suffice. By default, Valid returns true if the method IsValid returns true; otherwise, it calls Error to notify the user of the error, and then it returns false.


See Also

Member Function IsValid

Member Function IsValidInput

Member Function Error


Member Function IsValid (ObjectWindows)

See Also

The virtual member function IsValid is called by Valid, which passes IsValid the text string to be validated. IsValid returns true if the string represents valid data. IsValid does the actual data validation, so if you create your own validator objects, you will probably override IsValid.

Note:	 Do not call IsValid directly. Use Valid to call IsValid, because if IsValid returns false, Valid calls Error to alert the user. This behavior separates the validation role from the error-reporting role.


See Also

Member Function Valid

Member Function IsValidInput

Member Function Error


Member Function IsValidInput (ObjectWindows)

See Also

When an edit control object recognizes a keystroke event intended for it, it calls its validator's IsValidInput method to ensure that the entered character is a valid entry. By default, IsValidInput methods always return true, meaning that all keystrokes are acceptable, but some derived validators override IsValidInput to filter out unwanted keystrokes.

For example, range validators, which are used for numeric input, return true from IsValidInput only for numeric digits and the characters '+' and '-'.

IsValidInput takes two parameters, as shown in the following syntax statement:

virtual bool IsValidInput(char far* str, bool suppressFill);

The first parameter, str, points to the current input text being validated. The second parameter is a Boolean value indicating whether the validator should apply filling or padding to the input string before attempting to validate it. TPXPictureValidator is the only standard validator object that uses the second parameter.


See Also

Member Function Valid

Member Function IsValid

Member Function Error


Member Function Error (ObjectWindows)

See Also

Virtual member function Error alerts the user that the contents of the edit control do not pass the validation check. The standard validator objects generally present a simple message box notifying the user that the contents of the input are invalid and describing what proper input would be.

For example, the Error member function for a range validator object creates a message box indicating that the value in the edit control is not between the indicated minimum and maximum values.

Although most descendant validator objects override Error, you never call it directly. Valid calls Error for you if IsValid returns false, which is the only time Error needs to be called.


See Also

Member Function Valid

Member Function IsValid

Member Function IsValidInput


Visual Basic Control Objects Overview (ObjectWindows)

See Also

ObjectWindows lets you use Visual Basic (VBX) 1.0-compatible controls in your Windows applications as easily as you use standard Windows or ObjectWindows controls.

VBX controls offer a wide range of functionality that is not provided in standard Windows controls. There are numerous public domain and commercial packages of VBX controls that can be used to provide a more polished and useful user interface.

To take advantage of VBX controls, use the two ObjectWindows classes TVbxControl and TVbxEventHandler.

Using VBX Controls

To use VBX controls in your ObjectWindows application, follow this process:

1.	In your OwlMain function, call the function VBXInit before you call the Run function of your application object. Call the function VBXTerm after you call the Run function of your application object. VBXInit takes the application instance as a parameter. VBXTerm takes no parameters. These functions initialize and close each instance's host environment necessary for using VBX controls. Your OwlMain function might look something like this:

int OwlMain(int argc, char* argv[]) {

  VBXInit(_hInstance);

  return TApplication("Wow!").Run();

  VBXTerm();

}

2.	Derive a class that mixes your base interface class with TVbxEventHandler. Your base interface class is whatever class you want to display the control in. If you are using the control in a dialog box, you need to mix in TDialog. The code would look something like this:

class MyVbxDialog : public TDialog, public TVbxEventHandler

{

  public:

    MyVbxDialog(TWindow *parent, char *name)

      : TDialog(parent, name),

        TWindow(parent, name) {}

  DECLARE_RESPONSE_TABLE(MyVbxDialog);

};

3.	Build a response table for the parent, including all relevant events from your control. Use the EV_VBXEVENTNAME macro to set up the response for each control event.

4.	Create the control's parent. You can either construct the control when you create the parent or allow the parent to construct the control itself, depending on how the control is being used.


See Also

Accessing a VBX Control

Handling VBX Control Messages


TVbxControl Class (ObjectWindows)

See Also

TVbxControl provides the actual interface to the control by letting you:

Construct a VBX control object

Get and change control properties

Find the number of control properties and convert property names to and from property indexes

Find the number of control events and convert event names to and from event indexes

Call the Visual Basic 1.0 standard control methods AddItem, Move, Refresh, and RemoveItem

Get the handle to the control element using the TVbxControl member function GetHCTL

TVbxControl is derived from the class TControl, which is derived from TWindow. Thus, TVbxControl acts much the same as any other interface element based on TWindow.


See Also

Implicit and Explicit Construction

TVbxControl Constructors

TVbxEventHandler Class


TVbxControl Constructors (ObjectWindows)

See Also

TVbxControl has two constructors.

Dynamically Constructing a VBX Control

The first constructor lets you dynamically construct a VBX control by specifying a VBX control file name (for example, SWITCH.VBX), control ID, control class, control title, location, and size:

TVbxControl(TWindow *parent,

            int id,

            const char far *FileName,

            const char far *ClassName,

            const char far *title,

            int x, int y,

            int w, int h,

            TModule *module);

The parameters are described in the following table:

Parameter	Description

parent	A pointer to the control's parent.

id	The control's ID, used when defining the parent's response table. It usually looks like a resource ID.

FileName 	The name of the file that contains the VBX control, including a path name if necessary.

ClassName 	The class name of the control. A given VBX control file might contain a number of separate controls, each of which is identified by a unique class name (usually found in the control reference guide of third-party VBX control libraries).

title 	The control's title or caption.

x and y 	The coordinates within the parent object at which you want the control placed.

w and h 	The control's width and the height.

module 	Passed to the TControl base constructor as the TModule parameter for that constructor; defaults to 0.

Using a VBX control in the application's resource file

The second constructor lets you set a TVbxControl object using a VBX control that has been defined in the application's resource file:

TVbxControl(TWindow *parent,

            int resId,

            TModule *module);

This constructor's parameters are

Parameter	Description

parent	A pointer to the control's parent.

resid	The resource ID of the VBX control in the resource file.

module 	Passed to the TControl base constructor as the TModule parameter for that constructor; defaults to 0.


See Also

Implicit and Explicit Construction


Implicit and Explicit Construction (ObjectWindows)

See Also

You can construct VBX controls either explicitly or implicitly. You explicitly construct an object when you call one of the constructors. You implicitly construct an object when you do not call one of the constructors and allow the control to be instantiated and created by its parent.

Explicit Construction

Explicit construction involves calling either constructor of a VBX control object. This is normally done in the parent's constructor so that the VBX control is constructed and ready when the parent window is created. You can also wait to construct the control until it is needed. (You might want to do this if you had room for only one control.) In this latter case, you could let the user choose a menu choice or press a button. Then, depending what the user does, you would instantiate an object and display it in an existing interface element.

The following code demonstrates explicit construction using both of the TVbxControl constructors in the constructor of a dialog box object:

class TTestDialog : public TDialog, public TVbxEventHandler

{

  public:

    TTestDialog(TWindow *parent, char *name)

      : TDialog(parent, name), TWindow(parent, name)

    {

      new TVbxControl(this, IDCONTROL1);

      new TVbxControl(this, IDCONTROL2,

                      "SWITCH.VBX", "BiSwitch",

                      "&Program VBX Control",

                      16, 70, 200, 50);

    }

  DECLARE_RESPONSE_TABLE(TTestDialog);

};

Implicit Construction

Implicit construction takes place when you design your interface element outside your application source code, such as in Resource Workshop. You can use Resource Workshop to add VBX controls to dialog boxes and other interface elements. Then when you instantiate the parent object, the children, such as edit boxes, list boxes, buttons, and VBX controls, are automatically created along with the parent. The following code demonstrates how the code for this might look. It is important to note, however, that what you don't see in the following code is a VBX control. Instead, the VBX control is included in the dialog resource DIALOG_1. When DIALOG_1 is loaded and created, the VBX control is automatically created.

class TTestDialog : public TDialog, public TVbxEventHandler

{

  public:

    TTestDialog(TWindow *parent, char *name)

      : TDialog(parent, name), TWindow(parent, name) {}

  DECLARE_RESPONSE_TABLE(TTestDialog);

  };

void TTestWindow::CmAbout() {

  TTestDialog(this, "DIALOG_1").Execute();

  }


See Also

TVbxControl Constructors


TVbxEventHandler Class (ObjectWindows)

See Also

The TVbxEventHandler class is quite small and, for the most part, of little interest to most programmers. What it does is very important, though. Without the functionality contained in this class, you could not communicate with your VBX controls. The event-handling programming model is described in greater detail in Handling VBX Control Messages; this topic explains only the part that TVbxEventHandler plays in the process.

TVbxEventHandler consists of a single function and a one-message response table. The function, called EvVbxDispatch, is the event-handling routine for a message called WM_VBXFIREEVENT. EvVbxDispatch receives the WM_VBXFIREEVENT message, converts the uncracked message to a VBXEVENT structure, and dispatches a new message, which is handled by the control's parent. Because the parent object is necessarily derived from TVbxEventHandler, the parent calls back to itself with a different message. The new message is much easier to handle and understand. This is the message that is handled by the EV_VBXEVENTNAME macro.


See Also

TVbxControl Class


Handling VBX Control Messages (ObjectWindows)

See Also

You must handle VBX control messages through the control's parent object. For the parent object to be able to handle these messages, it must be derived from the class TVbxEventHandler. To accomplish this, you can mix whatever interface object class you want to use to contain the VBX control (for example, TDialog, TFrameWindow, or classes you might have derived from ObjectWindows interface classes) with the TVbxEventHandler class.


See Also

Event Response Table

Finding Event Information

Interpreting a Control Event


Event Response Table (ObjectWindows)

See Also

After you have derived your new class, you need to build a response table for it. The response table for this class looks like a normal response table; you still need to handle all the regular command messages and events you normally do. The only addition is the EV_VBXEVENTNAME macro to handle the new class of messages from your VBX controls.

The EV_VBXEVENTNAME macro is defined as follows:

EV_VBXEVENTNAME(ID, Event, EvHandler)

The three parameters are

Parameter	Description

ID 	The control ID. You can find this ID either as the second parameter to both constructors or as the resource ID in the resource file.

Event 	A string identifying the event name. This name is dependent on the control and can be one of the standard VBX event names or a custom event name. If the control is from a third-party VBX control library, you can find this event name by looking in the control reference guide.

EvHandler 	The handler function for this event and control. The EvHandler function has the following signature:

void EvHandler(VBXEVENT FAR *event);

When a message is received from a VBX control by its parent, the parent dispatches the message to the handler function that corresponds to the correct control and event. When it calls the function, the parent passes it a pointer to a VBXEVENT structure.


See Also

Finding Event Information

Interpreting a Control Event


Interpreting a Control Event (ObjectWindows)

See Also

After a VBX control event has taken place and the event-handling function has been called, the function must deal with the VBXEVENT structure received as a parameter. This structure looks like this:

struct VBXEVENT {

  HCTL    hCtl;

  HWND    hWnd;

  int     nID;

  int     iEvent;

  LPCSTR  lpszEvent;

  int     cParams;

  LPVOID  lpParams;

  };

The members are

Member	Description

hCtl 	The handle of the sending VBX control (not a window handle)

hWnd	The handle of the control window

nID 	The ID of the VBX control

iEvent 	The event index

lpszEvent 	The event name

cParams 	The number of parameters for this event

lpParams 	A pointer to an array containing pointers to the parameter values for this event

To understand the VBXEVENT structure, you need to understand how a VBX control event works. The first three members are straightforward: They let you identify the sending control. The next two members are also fairly simple: Each event that a VBX control can send has both an event index, represented by iEvent, and an event name, represented by lpszEvent.

The next two members, which store the parameters passed with the event, are more complex. cParams contains the total number of parameters available for this event. lpParams is an array of pointers to the event's parameters (like any other array, lpParam is indexed from 0 to cParams - 1). These two members are more complicated than the previous members because there is no inherent indication of the type or meaning of each parameter. If the control is from a third-party VBX control library, you can look in the control reference guide to find this information. Otherwise, you need to get the information from the designer of the control (or to have designed the control yourself).


See Also

Event Response Table

Finding Event Information


Finding Event Information (ObjectWindows)

See Also

The standard way to interpret the information returned by an event is to refer to the documentation for the VBX control. Failing that, TVbxControl provides a number of methods for obtaining information about an event.

You can find the total number of events that a control can send by using the TVbxControl member function GetNumEvents., which returns an int that gives the total number of events. These events are indexed from 0 to the return value of GetNumEvents - 1.

You can find the name of any event in this range by calling the TVbxControl member function GetEventName, which takes one parameter, an int index number, and returns a string containing the name of the event.

Conversely, you can find the index of an event by calling the TVbxControl member function GetEventIndex, which takes one parameter, a string containing the event name, and returns the corresponding int event index.


See Also

Event Response Table

Interpreting a Control Event


Accessing a VBX Control (ObjectWindows)

There are two ways you can directly access a VBX control.

One way is to get and set the properties of the control. A control has a fixed number of properties you can set to affect the look or behavior of the control.

The other way is to call the control's methods. A control's methods are similar to member functions in a class and are actually accessed through member functions in the TVbxControl class. You can use these methods to call into the object and cause an action to take place.


VBX Control Properties (ObjectWindows)

See Also

Every VBX control has a number of properties. Control properties affect the look and behavior of the control; for example, the colors used in various parts of the control, the size and location of the control, the control's caption, and so on. Changing these properties is usually your main way to manipulate a VBX control.

Each control's properties should be fully documented in the control reference guide of third-party VBX control libraries. If the control is not a third-party control or part of a commercial control package, then you need to consult the control's designer for any limits or special meanings to the control's properties. Many properties often function only as an index to a property. An example of this might be background patterns: 0 could mean plain, 1 could mean cross-hatched, 2 could mean black, and so on. Without the proper documentation or information, it can be difficult to use a control's properties.


See Also

Finding Property Information

Getting Control Properties

Setting Control Properties

VBX Control Methods


Finding Property Information (ObjectWindows)

See Also

The standard way to get information about a control's properties is to refer to the documentation for the VBX control. Failing that, TVbxControl provides a number of methods for obtaining information about a control's properties.

You can find the total number of properties for a control by calling the TVbxControl member function GetNumProps, which returns an int that gives the total number of properties. These properties are indexed from 0 to the return value of GetNumProps - 1.

You can find the name of any property in this range by calling the TVbxControl member function GetPropName, which takes one parameter, an int index number, and returns a string containing the name of the property.

Conversely, you can find the index of an property by calling the TVbxControl member function GetPropIndex, which takes one parameter, a string containing the property name, and returns the corresponding int property index.


See Also

Getting Control Properties

Setting Control Properties


Getting Control Properties (ObjectWindows)

See Also

You can get the value of a control property using either its name or its index number. Although using the index is more efficient (because there is no string lookup), using the property name is usually more intuitive. You can use either method, depending on your preference.

TVbxControl provides the function GetProp to get the properties of a control. GetProp is overloaded to allow use of either the index or the name of the property. Each of these versions is further overloaded to allow you to obtain different types of properties:

// get properties by index

bool GetProp(int propIndex, int& value, int arrayIndex = -1);

bool GetProp(int propIndex, long& value, int arrayIndex = -1);

bool GetProp(int propIndex, HPIC& value, int arrayIndex = -1);

bool GetProp(int propIndex, float& value, int arrayIndex = -1);

bool GetProp(int propIndex, string& value, int arrayIndex = -1);

// get properties by name

bool GetProp(const char far* name, int& value, int arrayIndex = -1);

bool GetProp(const char far* name, long& value, int arrayIndex = -1);

bool GetProp(const char far* name, HPIC& value, int arrayIndex = -1);

bool GetProp(const char far* name, float& value, int arrayIndex = -1);

bool GetProp(const char far* name, string& value, int arrayIndex = -1);

Parameter	Explanation

first parameter	In the versions where the first parameter is an int, you specify the property by passing in the property index. In the versions where the first parameter is a char *, you specify the property by passing in the property name.

second parameter	The second parameter of the function is a reference to an object with the same data type as the property. It is used by GetProp to return the property value. Create an object of the same type as the property and pass a reference to the object in value. When GetProp returns, the object contains the current value of the property.

third parameter	The third parameter is the index of an array property that you supply if the control requires it. Consult the documentation for your VBX control to discover if you need to supply this parameter and, if so, what the required values are. The function ignores this parameter if it is -1.


See Also

Finding Property Information

Setting Control Properties


Setting Control Properties (ObjectWindows)

See Also

As you do when you get control properties, you set the value of a control property by using either its name or its index number. Although using the index is more efficient (because there is no string lookup), using the property name is usually more intuitive. You can use either method, depending on your preference.

TVbxControl provides the function SetProp to set the properties of a control. SetProp is overloaded to allow you to set properties with either the index or name of the property. Each of these versions is further overloaded to allow you to set a number of different types of properties.

// set properties by index

bool SetProp(int propIndex, int value, int arrayIndex = -1);

bool SetProp(int propIndex, long value, int arrayIndex = -1);

bool SetProp(int propIndex, HPIC value, int arrayIndex = -1);

bool SetProp(int propIndex, float value, int arrayIndex = -1);

bool SetProp(int propIndex, const string& value,

             int arrayIndex = -1);

bool SetProp(int propIndex, const char far* value,

             int arrayIndex = -1);

// set properties by name

bool SetProp(const char far* name, int value, int arrayIndex = -1);

bool SetProp(const char far* name, long value, int arrayIndex = -1);

bool SetProp(const char far* name, HPIC value, int arrayIndex = -1);

bool SetProp(const char far* name, float value, int arrayIndex = -1);

bool SetProp(const char far* name, const string& value,

             int arrayIndex = -1);

bool SetProp(const char far* name, const char far* value,

             int arrayIndex = -1);

Parameter	Explanation

first parameter	In the versions where the first parameter is an int, you specify the property by passing the property index. In the versions where the first parameter is a char *, you specify the property by passing the property name.

second parameter	The second parameter is the value the property should be set to.

third parameter	The third parameter is the index of an array property that you supply if the control requires it. Consult the documentation for your VBX control to discover if you need to supply this parameter and, if so, what the required values are. The function ignores this parameter if it is -1.

Although there are five different data types you can pass to GetProp, SetProp provides for six different data types. The last two versions of each type of call use a char * and the ANSI string class to represent a string. These versions allow flexibility when passing a character string into a control.

GetProp uses casting to allow a char * to function effectively as a string object.


See Also

Finding Property Information

Getting Control Properties


VBX Control Methods (ObjectWindows)

See Also

Methods are functions contained in each VBX control that you can use to call into the control and cause an action to take place. TVbxControl provides compatibility with the following methods contained in Visual Basic 1.0-compatible controls:

Function	Explanation

Move(int x, int y, int w, int h)	Moves the control to the coordinates x and y and resizes the control to w pixels wide by h pixels high.

Refresh()	Refreshes the control's display area.

AddItem(int index, const char far *item)	Adds the item item to the control's list of items and gives the new item the index number index.

RemoveItem(int index)	Removes the item with the index number index.


See Also

VBX Control Properties


Writing DLL Functions Overview (ObjectWindows)

See Also

When writing DLL functions that will be called from an application, keep these things in mind:

Make calls to 16-bit DLL functions far calls, and make pointers specified as parameters and return values far pointers. You need to do this because a 16-bit DLL has different code and data segments than the calling application. This is not necessary for 32-bit DLLs. Use the _FAR macro to make your code portable between platforms.

Static data defined in a 16-bit DLL is global to all calling applications because 16-bit DLLs have one data segment that all 16-bit DLL instances share. Global data set by one caller can be accessed by another. If you need data to be private for a given caller of a 16-bit DLL, you need to dynamically allocate and manage the data yourself on a per-task basis. For 32-bit DLLs, static data is private for each process, except under Win32s.


See Also

DLL Entry and Exit Functions (ObjectWindows)

Exporting DLL Functions (ObjectWindows)

Implicit and Explicit Loading (ObjectWindows)

Importing (calling) DLL Functions (ObjectWindows)

Mixing Static and Dynamic-linked Libraries (ObjectWindows)

Using ObjectWindows as a DLL (ObjectWindows)

Writing Shared Classes (ObjectWindows)


DLL Entry and Exit Functions (ObjectWindows)

Windows requires that two functions be defined in every DLL: an entry function and an exit function.

16-bit DLLs	LibMain is the entry function and WEP (Windows Exit Procedure) is the exit function. LibMain is called by Windows for the first application that calls the DLL, and WEP is called by Windows for the last application that uses the DLL.

32-bit DLLs	DllEntryPoint serves as both the entry and exit function. DllEntryPoint is called each time the DLL is loaded or unloaded, each time a process attaches to or detaches from the DLL, and each time a thread within a process is created or destroyed.

Windows calls the entry procedure (LibMain or DllEntryPoint) once, when the library is first loaded. The entry procedure initializes the DLL; this initialization depends almost entirely on the particular DLL function, but might include the following tasks:

Unlocking the data segment with UnlockData, if it has been declared as MOVEABLE

Setting up global variables for the DLL, if it uses any

There is no need to initialize the heap because the DLL startup code (C0Dx.OBJ) initializes the local heap automatically.


LibMain (ObjectWindows)

See Also

The 16-bit DLL entry procedure, LibMain, is defined as follows:

int PASCAL LibMain(HINSTANCE hInstance, uint16 wDataSeg,

                   uint16 cbHeapSize, LPSTR lpCmdLine)

LibMain, HINSTANCE, uint16, and LPSTR are defined in windows.h. The parameters are described in the following table:

Parameter	Description

hInstance	instance handle of the DLL.

wDataSeg	value of the data segment (DS) register.

cbHeapSize	size of the local heap specified in the module definition file for the DLL.

lpCmdLine	far pointer to the command line specified when the DLL was loaded. This is almost always null, because typically DLLs are loaded automatically without parameters. It is possible, however, to supply a command line to a DLL when it is loaded explicitly.

The return value for LibMain is either 1 (successful initialization) or 0 (unsuccessful initialization). Windows unloads the DLL from memory if 0 is returned.


See Also

DllEntryPoint (ObjectWindows)

WEP (ObjectWindows)


WEP (ObjectWindows)

See Also

WEP is the exit procedure of a DLL. Windows calls it prior to unloading the DLL.  Because the Borland C++ run-time libraries provide a default WEP, this function is not necessary in a DLL, but you can write one to perform any cleanup before the DLL is unloaded from memory. Often the application has terminated by the time WEP is called, so valid options are limited.

Under Borland C++, WEP does not need to be exported, although you should export it if you are concerned with portability. WEP returns 1 to indicate success. Windows currently does not use this return value. Here is the WEP prototype:

int FAR PASCAL WEP (int nParameter)

The nParameter can be one of the following:

WEP_SYSTEMEXIT	Windows is shutting down.

WEP_FREE_DLL	Just this DLL is unloading.


See Also

DllEntryPoint (ObjectWindows)

LibMain (ObjectWindows)


DllEntryPoint (ObjectWindows)

See Also

The 32-bit DLL entry point, DllEntryPoint, is defined as follows:

bool WINAPI DllEntryPoint(HINSTANCE hinstDll, uint32 fdwReason,

                          LPVOID lpvReserved)

DllEntryPoint is defined in winbase.h. The parameters are as follows:

Parameter	Description

hinstDll	The DLL instance handle.

fdwReason	A flag that describes why the DLL is being called (either a process or thread). The flags can take the following values:

DLL_PROCESS_ATTACH
DLL_THREAD_ATTACH
DLL_THREAD_DETACH
DLL_PROCESS_DETACH

lpvReserved	Specifies further aspects of the DLL initialization and cleanup based on the value of fdwReason.


See Also

LibMain (ObjectWindows)

WEP (ObjectWindows)


Exporting DLL Functions (ObjectWindows)

See Also

After writing your DLL functions, you must export the functions that you want to be available to a calling application. There are two steps involved: compiling your DLL functions as exportable functions and exporting them. You can do this in the following ways:

If you flag a function with the _export keyword, it is compiled as exportable and is then exported.

If you add the _export keyword to a class declaration, the entire class (data and function members) is compiled as exportable and is exported.

If you do not flag a function with _export, use the appropriate compiler switch or IDE setting to compile functions as exportable. Then list the function in the module definition (.DEF) file EXPORTS section.


See Also

Importing (calling) DLL Functions (ObjectWindows)


Importing (calling) DLL Functions (ObjectWindows)

See Also

You call a DLL function from an application just as you would call a function defined in the application itself. However, you must import the DLL functions that your application calls.

To import a DLL function,

Add an IMPORTS section to the calling application's module definition (.DEF) file and list the DLL function as an import.

Link an import library that contains import information for the DLL function to the calling application. (Use IMPLIB to make the import library.)

Explicitly load the DLL using LoadLibrary and obtain function addresses using GetProcAddress.

When your application executes, the files for the called DLLs must be in one of the following locations, or your application will not be able to find the DLL files and will not load:

In the current directory

On the path

In the Windows or Windows system directory


See Also

Exporting DLL Functions (ObjectWindows)


Writing Shared Classes (ObjectWindows)

A class instance in a DLL can be shared among multiple applications. For example, you can share code that defines a dialog box by defining a shared dialog class in a DLL. The shared class can then be used in or derived from by other applications or DLLs. To share a class you need to export the class from the DLL and import the class into your application.

To define shared classes:

Conditionally declare your class as either _export or _import.

Pass a TModule* parameter to the window constructors (in some situations).

If you declare a shared class in an include file that is included by both the DLL and an application using the DLL, the class must be declared _export when compiling the DLL and _import when compiling the application. You can do this by defining a group of macros, one of which is conditionally set to _export when building the DLL and to _import when using the DLL. For example:

// BUILDEXAMPLEDLL is defined when building EXAMPLE as a DLL,

// but not when building it as a static library.

#if defined(BUILDEXAMPLEDLL)

   #define _EXAMPLECLASS __export

// USEEXAMPLEDLL is defined when building an application or DLL

// that uses EXAMPLE as a DLL.

#elif defined (USEEXAMPLEDLL)

   #define _EXAMPLECLASS __import

// This is used when compiling EXAMPLE as a static library.

#else

   #define _EXAMPLECLASS

#endif

class _EXAMPLECLASS TColorControl : public TControl {

  public:

  ...

};

By defining BUILDEXAMPLEDLL (on the command line, for example) when you are building the DLL, you cause _EXAMPLECLASS to expand to _export. This causes the class to be exported and shared by applications using the DLL.

By defining USEEXAMPLEDLL when you are building the application that will use the DLL, you cause _EXAMPLECLASS to expand to _import. The application will know what type of object it will import.


The TModule Object (ObjectWindows)

An instance of the TModule class serves as the object-oriented interface for an ObjectWindows DLL. TModule member functions provide support for window and memory management, and process errors.

The following code example shows the declaration and initialization of a TModule object. This example is conditionalized so that either 16-bit (LibMain) or 32-bit (DllEntryPoint) DLLs can use the same source file.

static TModule *ResMod;

#if defined(__WIN32__)

  bool WINAPI

  DllEntryPoint(HINSTANCE instance, uint32 /*flag*/, LPVOID)

#else   // !defined(__WIN32__)

  int

  FAR PASCAL

  LibMain(HINSTANCE instance,

    uint16      /*wDataSeg*/,

    uint16      /*cbHeapSize*/,

    char far* /*cmdLine*/)

#endif

  {

    // We are using the DLL and want to use the DLL's resources

    //

    if (!ResMod)

      ResMod = new TModule(0,instance);

    return true;

  }

Within the entry point function the TModule object ResMod is initialized with the instance handle of the DLL. If the module is not loaded an exception is thrown.

If your DLL requires additional initialization and cleanup, you can perform this processing in your LibMain, DllEntryPoint, or WEP functions. A better method, though, is to derive a TModule class, define data members for data global to your DLL within the class, and perform the required initialization and cleanup in its constructor and destructor.

After you have compiled and linked your DLL, use IMPLIB to generate an import library for your DLL. This import library will list all exported member functions from your shared classes as well as any ordinary functions you have exported.


Using ObjectWindows as a DLL (ObjectWindows)

See Also

To enable your ObjectWindows applications to share the ObjectWindows library, you can dynamically link them to the ObjectWindows DLL. To do this:

1.	When compiling, define the macro _OWLDLL on the compiler command line or in the IDE.

2.	Instead of specifying the static-link ObjectWindows library when linking (that is, OWLWS.LIB, OWLWM.LIB, OWLWL.LIB, or OWLWF.LIB), specify the ObjectWindows DLL import library (OWLWI.LIB for 16-bit applications, or OWLWFI.LIB for 32-bit applications).


See Also

Calling an ObjectWindows DLL

Implicit and Explicit Loading (ObjectWindows)

Mixing Static and Dynamic-linked Libraries (ObjectWindows)


Calling an ObjectWindows DLL

See Also

When both a child window and the parent window are created in an ObjectWindows application, communication between the parent and child windows is in place. But you can also prepare your DLL for use by non-ObjectWindows applications.

When a child window is created in an ObjectWindows DLL and the parent window is created by a non-ObjectWindows application, the parent-child relationship must be simulated in the ObjectWindows DLL. This is done by constructing an alias window object in the ObjectWindows DLL that is associated with the parent window whose handle is specified on a DLL call.

In the following code, the exported function CreateDLLWindow is in an ObjectWindows DLL. The function will work for both ObjectWindows and non-ObjectWindows applications.

bool far _export

CreateDLLWindow(HWND parentHWnd)

{

  TWindow* parentAlias =
      GetWindowPtr(parentHWnd);  // check if an OWL window

  if (!parentAlias)

    parentAlias = new TWindow(parentHWnd); // if not, make an alias

  TWindow* window = new TWindow(parentAlias, "Hello from a DLL!");

  window->Attr.Style |= WS_POPUPWINDOW | WS_CAPTION | WS_THICKFRAME

                     | WS_MINIMIZEBOX | WS_MAXIMIZEBOX;

  window->Attr.X = 100; window->Attr.Y = 100;

  window->Attr.W = 300; window->Attr.H = 300;

  return window->Create();

}

CreateDLLWindow determines if it has been passed a non-ObjectWindows window handle by the call to GetWindowPtr, which returns 0 when passed a non-ObjectWindows window handle. If it is a non-ObjectWindows window handle, an alias parent TWindow object is constructed to serve as the parent window.


See Also

Implicit and Explicit Loading (ObjectWindows)

Mixing Static and Dynamic-linked Libraries (ObjectWindows)


Implicit and Explicit Loading (ObjectWindows)

See Also

Implicit loading is done when you use a .DEF or import library to link your application. The DLL is loaded by Windows when the application using the DLL is loaded.

Explicit loading is used to load DLLs at run time and requires the use of the Windows API functions LoadLibrary to load the DLL and GetProcAddress to return DLL function addresses.


See Also

Mixing Static and Dynamic-linked Libraries (ObjectWindows)


Mixing Static and Dynamic-linked Libraries (ObjectWindows)

See Also

The ObjectWindows libraries are built using the BIDS (container class) libraries, which in turn are built using the C run-time library.

If you link with the DLL version of the ObjectWindows libraries, you must link with the DLL version of the BIDS and run-time libraries. You do this by defining the _OWLDLL macro. This is not the only combination of static and dynamic-linked libraries you can use: Each line in the table below lists an allowable combinations of static and dynamic-linked libraries.

Allowable library combinations

STATIC	DLL

OWL, BIDS, RTL	(none)

OWL, BIDS	RTL

OWL	BIDS, RTL

(none)	OWL, BIDS, RTL


See Also

Implicit and Explicit Loading (ObjectWindows)


Dynamic-link Library (ObjectWindows)

A dynamic-link library (DLL) is a library of functions, data, and resources whose references are resolved at run time rather than at compile time.

Applications that use code from static-linked libraries attach copies of that code at link time. Applications that use code from DLLs share that code with all other applications using the DLL, therefore reducing application size. For example, you might want to define in an ObjectWindows DLL complex windowing behavior shared by a group of your applications.