docs/latex/wx/odcbox.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        odcbox.tex
   3 %% Purpose:     wxOwnerDrawnComboBox docs
   4 %% Author:      Jaakko Salli
   5 %% Modified by:
   6 %% Created:
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) Jaakko Salli
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxOwnerDrawnComboBox}}\label{wxownerdrawncombobox}
  13
  14 wxOwnerDrawnComboBox is a combobox with owner-drawn list items.
  15 In essence, it is a \helpref{wxComboCtrl}{wxcomboctrl} with
  16 \helpref{wxVListBox}{wxvlistbox} popup and \helpref{wxControlWithItems}{wxcontrolwithitems}
  17 interface.
  18
  19 Implementing item drawing and measuring is similar to \helpref{wxVListBox}{wxvlistbox}.
  20 Application needs to subclass wxOwnerDrawnComboBox and implement
  21 \helpref{OnDrawItem()}{wxownerdrawncomboboxondrawitem}, \helpref{OnMeasureItem()}{wxownerdrawncomboboxonmeasureitem}
  22 and \helpref{OnMeasureItemWidth()}{wxownerdrawncomboboxonmeasureitemwidth}.
  23
  24
  25 \wxheading{Derived from}
  26
  27 \helpref{wxComboCtrl}{wxcomboctrl}\\
  28 \helpref{wxControlWithItems}{wxcontrolwithitems}\\
  29 \helpref{wxControl}{wxcontrol}\\
  30 \helpref{wxWindow}{wxwindow}\\
  31 \helpref{wxEvtHandler}{wxevthandler}\\
  32 \helpref{wxObject}{wxobject}
  33
  34 \wxheading{Include files}
  35
  36 <odcombo.h>
  37
  38 \wxheading{Window styles}
  39
  40 \begin{twocollist}\itemsep=0pt
  41 \twocolitem{\windowstyle{wxODCB\_DCLICK\_CYCLES}}{Double-clicking cycles item
  42 if wxCB\_READONLY is also used. Synonymous with wxCC\_SPECIAL\_DCLICK.}
  43 \twocolitem{\windowstyle{wxODCB\_STD\_CONTROL\_PAINT}}{Control itself is not
  44 custom painted using OnDrawItem. Even if this style is not used, writable
  45 wxOwnerDrawnComboBox is never custom painted unless SetCustomPaintWidth is
  46 called.}
  47 \end{twocollist}
  48
  49 See also \helpref{wxComboCtrl window styles}{wxcomboctrl} and
  50 base \helpref{window styles overview}{windowstyles}.
  51
  52 \wxheading{Event handling}
  53
  54 \twocolwidtha{7cm}
  55 \begin{twocollist}\itemsep=0pt
  56 \twocolitem{{\bf EVT\_COMBOBOX(id, func)}}{Process a wxEVT\_COMMAND\_COMBOBOX\_SELECTED event,
  57 when an item on the list is selected. Note that calling
  58 \helpref{GetValue}{wxcomboctrlgetvalue} returns the new value of selection.}
  59 \end{twocollist}
  60
  61 See also events emitted by \helpref{wxComboCtrl}{wxcomboctrl}.
  62
  63 \wxheading{See also}
  64
  65 \helpref{wxComboCtrl}{wxcomboctrl}, \helpref{wxComboBox}{wxcombobox}, \helpref{wxVListBox}{wxvlistbox},
  66 \rtfsp\helpref{wxCommandEvent}{wxcommandevent}
  67
  68
  69 \latexignore{\rtfignore{\wxheading{Members}}}
  70
  71
  72 \membersection{wxOwnerDrawnComboBox::wxOwnerDrawnComboBox}\label{wxownerdrawncomboboxctor}
  73
  74 \func{}{wxOwnerDrawnComboBox}{\void}
  75
  76 Default constructor.
  77
  78 \func{}{wxOwnerDrawnComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
  79 \param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
  80 \param{int}{ n = 0}, \param{const wxString }{choices[] = NULL},\rtfsp
  81 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
  82
  83 \func{}{wxOwnerDrawnComboBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
  84 \param{const wxString\& }{value}, \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp
  85 \param{const wxArrayString\& }{choices},\rtfsp
  86 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
  87
  88 Constructor, creating and showing a owner-drawn combobox.
  89
  90 \wxheading{Parameters}
  91
  92 \docparam{parent}{Parent window. Must not be NULL.}
  93
  94 \docparam{id}{Window identifier. A value of -1 indicates a default value.}
  95
  96 \docparam{value}{Initial selection string. An empty string indicates no selection.}
  97
  98 \docparam{pos}{Window position.}
  99
 100 \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized
 101 appropriately.}
 102
 103 \docparam{n}{Number of strings with which to initialise the control.}
 104
 105 \docparam{choices}{An array of strings with which to initialise the control.}
 106
 107 \docparam{style}{Window style. See \helpref{wxOwnerDrawnComboBox}{wxownerdrawncombobox}.}
 108
 109 \docparam{validator}{Window validator.}
 110
 111 \docparam{name}{Window name.}
 112
 113 \wxheading{See also}
 114
 115 \helpref{wxOwnerDrawnComboBox::Create}{wxownerdrawncomboboxcreate}, \helpref{wxValidator}{wxvalidator}
 116
 117
 118 \membersection{wxOwnerDrawnComboBox::\destruct{wxOwnerDrawnComboBox}}\label{wxownerdrawncomboboxdtor}
 119
 120 \func{}{\destruct{wxOwnerDrawnComboBox}}{\void}
 121
 122 Destructor, destroying the owner-drawn combobox.
 123
 124
 125 \membersection{wxOwnerDrawnComboBox::Create}\label{wxownerdrawncomboboxcreate}
 126
 127 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 128 \param{const wxString\& }{value = ``"}, \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 129 \param{int}{ n}, \param{const wxString }{choices[]},\rtfsp
 130 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
 131
 132 \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp
 133 \param{const wxString\& }{value}, \param{const wxPoint\&}{ pos}, \param{const wxSize\&}{ size},\rtfsp
 134 \param{const wxArrayString\& }{choices},\rtfsp
 135 \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``comboBox"}}
 136
 137 Creates the combobox for two-step construction. Derived classes
 138 should call or replace this function. See
 139 \helpref{wxOwnerDrawnComboBox::wxOwnerDrawnComboBox}{wxownerdrawncomboboxctor}\rtfsp
 140 for further details.
 141
 142
 143 \membersection{wxOwnerDrawnComboBox::GetWidestItem}\label{wxownerdrawncomboboxgetwidestitem}
 144
 145 \constfunc{int}{GetWidestItem}{\void}
 146
 147 Returns index to the widest item in the list.
 148
 149
 150 \membersection{wxOwnerDrawnComboBox::GetWidestItemWidth}\label{wxownerdrawncomboboxgetwidestitemwidth}
 151
 152 \constfunc{int}{GetWidestItemWidth}{\void}
 153
 154 Returns width of the widest item in the list.
 155
 156
 157 \membersection{wxOwnerDrawnComboBox::OnDrawBackground}\label{wxownerdrawncomboboxondrawbackground}
 158
 159 \constfunc{void}{OnDrawBackground}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{item}, \param{int }{flags}}
 160
 161 This method is used to draw the items background and, maybe, a border around it.
 162
 163 The base class version implements a reasonable default behaviour which consists
 164 in drawing the selected item with the standard background colour and drawing a
 165 border around the item if it is either selected or current.
 166
 167 \wxheading{Remarks}
 168
 169 \arg{flags} has the same meaning as with \helpref{OnDrawItem}{wxownerdrawncomboboxondrawitem}.
 170
 171
 172 \membersection{wxOwnerDrawnComboBox::OnDrawItem}\label{wxownerdrawncomboboxondrawitem}
 173
 174 \constfunc{void}{OnDrawItem}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{int }{item}, \param{int }{flags}}
 175
 176 The derived class may implement this function to actually draw the item
 177 with the given index on the provided DC. If function is not implemented,
 178 the item text is simply drawn, as if the control was a normal combobox.
 179
 180 \wxheading{Parameters}
 181
 182 \docparam{dc}{The device context to use for drawing}
 183
 184 \docparam{rect}{The bounding rectangle for the item being drawn (DC clipping
 185 region is set to this rectangle before calling this function)}
 186
 187 \docparam{item}{The index of the item to be drawn}
 188
 189 \docparam{flags}{Combines any of the following flag values:}
 190
 191 \twocolwidtha{7cm}%
 192 \begin{twocollist}\itemsep=0pt
 193 \twocolitem{{\tt wxODCB\_PAINTING\_CONTROL}}{Combo control is being
 194 painted, instead of a list item. Argument item may be wxNOT\_FOUND in this
 195 case.}
 196 \twocolitem{{\tt wxODCB\_PAINTING\_SELECTED}}{An item with selection
 197 background is being painted. DC text colour should already be correct.}
 198 \end{twocollist}
 199
 200
 201 \membersection{wxOwnerDrawnComboBox::OnMeasureItem}\label{wxownerdrawncomboboxonmeasureitem}
 202
 203 \constfunc{wxCoord}{OnMeasureItem}{\param{size\_t }{item}}
 204
 205 The derived class may implement this method to return the height of the
 206 specified item (in pixels).
 207
 208 The default implementation returns text height, as if this control was
 209 a normal combobox.
 210
 211
 212 \membersection{wxOwnerDrawnComboBox::OnMeasureItemWidth}\label{wxownerdrawncomboboxonmeasureitemwidth}
 213
 214 \constfunc{wxCoord}{OnMeasureItemWidth}{\param{size\_t }{item}}
 215
 216 The derived class may implement this method to return the width of the
 217 specified item (in pixels). If -1 is returned, then the item text width
 218 is used.
 219
 220 The default implementation returns -1.
 221