2a368fec9f
We can't make wxClientDC work on the platforms not supporting drawing outside of wxEVT_PAINT handler, but at least document that this doesn't work. Also add an example of using this class for the purpose for which it still works (measuring) and remove references to it and wxWindowDC from wxPaintDC documentation as we don't want to encourage people using it. See #17820.
123 lines
3.9 KiB
Objective-C
123 lines
3.9 KiB
Objective-C
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: dcclient.h
|
|
// Purpose: interface of wxClientDC and wxPaintDC
|
|
// Author: wxWidgets team
|
|
// Licence: wxWindows licence
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
/**
|
|
@class wxPaintDC
|
|
|
|
A wxPaintDC must be constructed if an application wishes to paint on the
|
|
client area of a window from within an EVT_PAINT() event handler. This
|
|
should normally be constructed as a temporary stack object; don't store a
|
|
wxPaintDC object. If you have an EVT_PAINT() handler, you @e must create a
|
|
wxPaintDC object within it even if you don't actually use it.
|
|
|
|
Using wxPaintDC within your EVT_PAINT() handler is important because it
|
|
automatically sets the clipping area to the damaged area of the window.
|
|
Attempts to draw outside this area do not appear.
|
|
|
|
A wxPaintDC object is initialized to use the same font and colours as the
|
|
window it is associated with.
|
|
|
|
@library{wxcore}
|
|
@category{dc}
|
|
|
|
@see wxDC, wxClientDC, wxMemoryDC, wxWindowDC, wxScreenDC
|
|
*/
|
|
class wxPaintDC : public wxClientDC
|
|
{
|
|
public:
|
|
/**
|
|
Constructor. Pass a pointer to the window on which you wish to paint.
|
|
*/
|
|
wxPaintDC(wxWindow* window);
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@class wxClientDC
|
|
|
|
wxClientDC is primarily useful for obtaining information about the window
|
|
from outside EVT_PAINT() handler.
|
|
|
|
Typical use of this class is to obtain the extent of some text string in
|
|
order to allocate enough size for a window, e.g.
|
|
@code
|
|
// Create the initially empty label with the size big enough to show
|
|
// the given string.
|
|
wxClientDC dc(this);
|
|
wxStaticText* text = new wxStaticText
|
|
(
|
|
this, wxID_ANY, "",
|
|
wxPoint(),
|
|
dc.GetTextExtent("String of max length"),
|
|
wxST_NO_AUTORESIZE
|
|
);
|
|
}
|
|
@endcode
|
|
|
|
@note While wxClientDC may also be used for drawing on the client area of a
|
|
window from outside an EVT_PAINT() handler in some ports, this does @em not
|
|
work on all platforms (neither wxOSX nor wxGTK with GTK 3 Wayland backend
|
|
support this, so drawing using wxClientDC simply doesn't have any effect
|
|
there) and the only portable way of drawing is via wxPaintDC. To redraw a
|
|
small part of the window, use wxWindow::RefreshRect() to invalidate just
|
|
this part and check wxWindow::GetUpdateRegion() in the paint event handler
|
|
to redraw this part only.
|
|
|
|
wxClientDC objects should normally be constructed as temporary stack
|
|
objects, i.e. don't store a wxClientDC object.
|
|
|
|
A wxClientDC object is initialized to use the same font and colours as the
|
|
window it is associated with.
|
|
|
|
@library{wxcore}
|
|
@category{dc}
|
|
|
|
@see wxDC, wxMemoryDC, wxPaintDC, wxWindowDC, wxScreenDC
|
|
*/
|
|
class wxClientDC : public wxWindowDC
|
|
{
|
|
public:
|
|
/**
|
|
Constructor. Pass a pointer to the window on which you wish to paint.
|
|
*/
|
|
wxClientDC(wxWindow* window);
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@class wxWindowDC
|
|
|
|
A wxWindowDC must be constructed if an application wishes to paint on the
|
|
whole area of a window (client and decorations). This should normally be
|
|
constructed as a temporary stack object; don't store a wxWindowDC object.
|
|
|
|
To draw on a window from inside an EVT_PAINT() handler, construct a
|
|
wxPaintDC object instead.
|
|
|
|
To draw on the client area of a window from outside an EVT_PAINT() handler,
|
|
construct a wxClientDC object.
|
|
|
|
A wxWindowDC object is initialized to use the same font and colours as the
|
|
window it is associated with.
|
|
|
|
@library{wxcore}
|
|
@category{dc}
|
|
|
|
@see wxDC, wxMemoryDC, wxPaintDC, wxClientDC, wxScreenDC
|
|
*/
|
|
class wxWindowDC : public wxDC
|
|
{
|
|
public:
|
|
/**
|
|
Constructor. Pass a pointer to the window on which you wish to paint.
|
|
*/
|
|
wxWindowDC(wxWindow* window);
|
|
};
|
|
|