From: Bryan Petty Date: Fri, 31 Oct 2008 01:22:58 +0000 (+0000) Subject: Reviewed some g* interface headers. X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/23d291c2d2e8d6bfd9e4a569d735dd8ff61a10f7 Reviewed some g* interface headers. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56606 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/interface/wx/gdiobj.h b/interface/wx/gdiobj.h index e7aeca6687..ab6cbf4ec6 100644 --- a/interface/wx/gdiobj.h +++ b/interface/wx/gdiobj.h @@ -9,18 +9,16 @@ /** @class wxGDIObject - This class allows platforms to implement functionality to optimise GDI objects, - such - as wxPen, wxBrush and wxFont. On Windows, the underling GDI objects are a - scarce resource - and are cleaned up when a usage count goes to zero. On some platforms this - class may not have any special functionality. + This class allows platforms to implement functionality to optimise GDI + objects, such as wxPen, wxBrush and wxFont. On Windows, the underling GDI + objects are a scarce resource and are cleaned up when a usage count goes to + zero. On some platforms this class may not have any special functionality. Since the functionality of this class is platform-specific, it is not documented here in detail. @library{wxcore} - @category{FIXME} + @category{gdi} @see wxPen, wxBrush, wxFont */ @@ -32,4 +30,3 @@ public: */ wxGDIObject(); }; - diff --git a/interface/wx/glcanvas.h b/interface/wx/glcanvas.h index 3eefc74a3b..887e55d76d 100644 --- a/interface/wx/glcanvas.h +++ b/interface/wx/glcanvas.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: glcanvas.h -// Purpose: interface of wxGLContext +// Purpose: interface of wxGLContext and wxGLCanvas // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -9,30 +9,29 @@ /** @class wxGLContext - An instance of a wxGLContext represents the state of an OpenGL state machine - and the connection between OpenGL and the system. + An instance of a wxGLContext represents the state of an OpenGL state + machine and the connection between OpenGL and the system. The OpenGL state includes everything that can be set with the OpenGL API: - colors, rendering variables, display lists, texture objects, etc. - Although it is possible to have multiple rendering contexts share display lists - in order to save resources, - this method is hardly used today any more, because display lists are only a - tiny fraction of the overall state. + colors, rendering variables, display lists, texture objects, etc. Although + it is possible to have multiple rendering contexts share display lists in + order to save resources, this method is hardly used today any more, because + display lists are only a tiny fraction of the overall state. Therefore, one rendering context is usually used with or bound to multiple - output windows in turn, - so that the application has access to the complete and identical state while - rendering into each window. + output windows in turn, so that the application has access to the complete + and identical state while rendering into each window. Binding (making current) a rendering context with another instance of a - wxGLCanvas however works only - if the other wxGLCanvas was created with the same attributes as the wxGLCanvas - from which the wxGLContext - was initialized. (This applies to sharing display lists among contexts + wxGLCanvas however works only if the other wxGLCanvas was created with the + same attributes as the wxGLCanvas from which the wxGLContext was + initialized. (This applies to sharing display lists among contexts analogously.) - Note that some wxGLContext features are extremely platform-specific - its best - to check your native platform's glcanvas header (on windows include/wx/msw/glcanvas.h) to see what features your native platform provides. + Note that some wxGLContext features are extremely platform-specific - its + best to check your native platform's glcanvas header (on windows + include/wx/msw/glcanvas.h) to see what features your native platform + provides. @library{wxgl} @category{gl} @@ -46,36 +45,40 @@ public: Constructor. @param win - The canvas that is used to initialize this context. This parameter is - needed only temporarily, - and the caller may do anything with it (e.g. destroy the window) after the - constructor returned. - It will be possible to bind (make current) this context to any other - wxGLCanvas that has been created - with equivalent attributes as win. + The canvas that is used to initialize this context. This parameter + is needed only temporarily, and the caller may do anything with it + (e.g. destroy the window) after the constructor returned. @n + It will be possible to bind (make current) this context to any + other wxGLCanvas that has been created with equivalent attributes + as win. @param other - Context to share display lists with or @NULL (the default) for no sharing. + Context to share display lists with or @NULL (the default) for no + sharing. */ wxGLContext(wxGLCanvas* win, const wxGLContext* other = NULL); /** - Makes the OpenGL state that is represented by this rendering context current - with the wxGLCanvas @e win. - Note that @a win can be a different wxGLCanvas window than the one that was - passed to the constructor of this rendering context. - If @e RC is an object of type wxGLContext, the statements @e - RC.SetCurrent(win); and @e win.SetCurrent(RC); are equivalent, - see wxGLCanvas::SetCurrent. + Makes the OpenGL state that is represented by this rendering context + current with the wxGLCanvas @e win. + + @note @a win can be a different wxGLCanvas window than the one that was + passed to the constructor of this rendering context. If @e RC is + an object of type wxGLContext, the statements + @e "RC.SetCurrent(win);" and @e "win.SetCurrent(RC);" are + equivalent, see wxGLCanvas::SetCurrent(). */ virtual bool SetCurrent(const wxGLCanvas& win) const; }; /** + @anchor wxGL_FLAGS + Constants for use with wxGLCanvas. - Notice that not all implementation support options such as stereo, - auxiliary buffers, alpha channel, and accumulator buffer, use - wxGLCanvas::IsDisplaySupported() to check for individual attributes support. + @note Not all implementations support options such as stereo, auxiliary + buffers, alpha channel, and accumulator buffer, use + wxGLCanvas::IsDisplaySupported() to check for individual attributes + support. */ enum { @@ -139,36 +142,33 @@ enum @class wxGLCanvas wxGLCanvas is a class for displaying OpenGL graphics. It is always used in - conjunction with wxGLContext as the context can only be - be made current (i.e. active for the OpenGL commands) when it is associated to - a wxGLCanvas. - - More precisely, you first need to create a wxGLCanvas window and then create an - instance of a wxGLContext that is initialized with this - wxGLCanvas and then later use either wxGLCanvas::SetCurrent - with the instance of the wxGLContext or - wxGLContext::SetCurrent with the instance of - the wxGLCanvas (which might be not the same as was used - for the creation of the context) to bind the OpenGL state that is represented - by the rendering context to the canvas, and then finally call - wxGLCanvas::SwapBuffers to swap the buffers of - the OpenGL canvas and thus show your current output. + conjunction with wxGLContext as the context can only be made current (i.e. + active for the OpenGL commands) when it is associated to a wxGLCanvas. + + More precisely, you first need to create a wxGLCanvas window and then + create an instance of a wxGLContext that is initialized with this + wxGLCanvas and then later use either SetCurrent() with the instance of the + wxGLContext or wxGLContext::SetCurrent() with the instance of the + wxGLCanvas (which might be not the same as was used for the creation of the + context) to bind the OpenGL state that is represented by the rendering + context to the canvas, and then finally call SwapBuffers() to swap the + buffers of the OpenGL canvas and thus show your current output. Notice that previous versions of wxWidgets used to implicitly create a - wxGLContext inside wxGLCanvas itself. This is still supported in the current - version but is deprecated now and will be removed in the future, please update - your code to create the rendering contexts explicitly. + wxGLContext inside wxGLCanvas itself. This is still supported in the + current version but is deprecated now and will be removed in the future, + please update your code to create the rendering contexts explicitly. - To set up the attributes for the canvas (number of bits for the depth buffer, - number of bits for the stencil buffer and so on) you should set up the correct - values of - the @e attribList parameter. The values that should be set up and their - meanings will be described below. + To set up the attributes for the canvas (number of bits for the depth + buffer, number of bits for the stencil buffer and so on) you should set up + the correct values of the @e attribList parameter. The values that should + be set up and their meanings will be described below. - Notice that OpenGL is not enabled by default. To switch it on, you need to edit - setup.h under Windows and set @c wxUSE_GLCANVAS to 1 (you may also need - to have to add @c opengl32.lib and @c glu32.lib to the list of libraries - your program is linked with). On Unix, pass @c --with-opengl to configure. + @note OpenGL is not enabled by default. To switch it on, you need to edit + setup.h under Windows and set @c wxUSE_GLCANVAS to 1 (you may also + need to have to add @c opengl32.lib and @c glu32.lib to the list of + libraries your program is linked with). On Unix, pass + @c --with-opengl to configure. @library{wxgl} @category{gl} @@ -179,24 +179,24 @@ class wxGLCanvas : public wxWindow { public: /** - Creates a window with the given parameters. Notice that you need to create and - use a wxGLContext to output to this window. - If + Creates a window with the given parameters. Notice that you need to + create and use a wxGLContext to output to this window. - @param attribList is not specified, double buffered RGBA mode is used. + If @a attribList is not specified, double buffered RGBA mode is used. - parent + @param parent Pointer to a parent window. @param id Window identifier. If -1, will automatically create an identifier. @param pos Window position. wxDefaultPosition is (-1, -1) which indicates that - wxWidgets - should generate a default position for the window. + wxWidgets should generate a default position for the window. @param size - Window size. wxDefaultSize is (-1, -1) which indicates that wxWidgets should - generate a default size for the window. If no suitable size can be found, - the window will be sized to 20x20 pixels so that the window is visible but obviously not correctly sized. + Window size. wxDefaultSize is (-1, -1) which indicates that + wxWidgets should generate a default size for the window. If no + suitable size can be found, the window will be sized to 20x20 + pixels so that the window is visible but obviously not correctly + sized. @param style Window style. @param name @@ -204,24 +204,24 @@ public: @param attribList Array of integers. With this parameter you can set the device context attributes associated to this window. This array is - zero-terminated: it should be set up with constants described in - the table above. If a constant should be followed by a value, put - it in the next array position. For example, the WX_GL_DEPTH_SIZE - should be followed by the value that indicates the number of bits - for the depth buffer, e.g: + zero-terminated: it should be set up using @ref wxGL_FLAGS + constants. If a constant should be followed by a value, put it in + the next array position. For example, WX_GL_DEPTH_SIZE should be + followed by the value that indicates the number of bits for the + depth buffer, e.g: @code attribList[n++] = WX_GL_DEPTH_SIZE; attribList[n++] = 32; attribList[n] = 0; // terminate the list @endcode If the attribute list is not specified at all, i.e. if this - parameter is @NULL, the default attributes including @c WX_GL_RGBA - and @c WX_GL_DOUBLEBUFFER are used. But notice that if you do - specify some attributes you also need to explicitly include these - two default attributes in the list if you need them. + parameter is @NULL, the default attributes including WX_GL_RGBA and + WX_GL_DOUBLEBUFFER are used. But notice that if you do specify some + attributes you also need to explicitly include these two default + attributes in the list if you need them. @param palette - Palette for indexed colour (i.e. non WX_GL_RGBA) mode. - Ignored under most platforms. + Palette for indexed colour (i.e. non WX_GL_RGBA) mode. Ignored + under most platforms. */ wxGLCanvas(wxWindow* parent, wxWindowID id = wxID_ANY, const int* attribList = NULL, @@ -233,37 +233,42 @@ public: /** Determines if a canvas having the specified attributes is available. - Returns @true if attributes are supported. @param attribList - See attribList for wxGLCanvas(). + See @a attribList for wxGLCanvas(). + + @return @true if attributes are supported. */ static bool IsDisplaySupported(const int* attribList = NULL); /** - Sets the current colour for this window (using @c glcolor3f()), using the - wxWidgets colour database to find a named colour. + Sets the current colour for this window (using @c glcolor3f()), using + the wxWidgets colour database to find a named colour. */ bool SetColour(const wxString& colour); /** - Makes the OpenGL state that is represented by the OpenGL rendering context - @a context current, i.e. it will be used by all subsequent OpenGL calls. - This is equivalent to wxGLContext::SetCurrent - called with this window as parameter. - Note that this function may only be called when the window is shown on screen, - in particular it can't usually be called from the constructor as the window - isn't yet shown at this moment. - Returns @false if an error occurred. + Makes the OpenGL state that is represented by the OpenGL rendering + context @a context current, i.e. it will be used by all subsequent + OpenGL calls. + + This is equivalent to wxGLContext::SetCurrent() called with this window + as parameter. + + @note This function may only be called when the window is shown on + screen, in particular it can't usually be called from the + constructor as the window isn't yet shown at this moment. + + @return @false if an error occurred. */ bool SetCurrent(const wxGLContext context); /** - Swaps the double-buffer of this window, making the back-buffer the front-buffer - and vice versa, - so that the output of the previous OpenGL commands is displayed on the window. - Returns @false if an error occurred. + Swaps the double-buffer of this window, making the back-buffer the + front-buffer and vice versa, so that the output of the previous OpenGL + commands is displayed on the window. + + @return @false if an error occurred. */ virtual bool SwapBuffers(); }; - diff --git a/interface/wx/graphics.h b/interface/wx/graphics.h index 491abe5f91..190aed1da3 100644 --- a/interface/wx/graphics.h +++ b/interface/wx/graphics.h @@ -9,67 +9,74 @@ /** @class wxGraphicsPath - A wxGraphicsPath is a native representation of an geometric path. The contents - are specific an private to the respective renderer. Instances are ref counted and can - therefore be assigned as usual. The only way to get a valid instance is via - wxGraphicsContext::CreatePath or wxGraphicsRenderer::CreatePath. + A wxGraphicsPath is a native representation of a geometric path. The + contents are specific an private to the respective renderer. Instances are + reference counted and can therefore be assigned as usual. The only way to + get a valid instance is by using wxGraphicsContext::CreatePath() or + wxGraphicsRenderer::CreatePath(). @library{wxcore} - @category{FIXME} + @category{gdi} */ class wxGraphicsPath : public wxGraphicsObject { public: - //@{ /** - + Adds an arc of a circle centering at (@a x,@a y) with radius (@a r) + from @a startAngle to @a endAngle. + */ + virtual void AddArc(wxDouble x, wxDouble y, wxDouble r, + wxDouble startAngle, wxDouble endAngle, + bool clockwise); + /** + Adds an arc of a circle centering at @a c with radius (@a r) + from @a startAngle to @a endAngle. */ - void AddArc(wxDouble x, wxDouble y, wxDouble r, - wxDouble startAngle, - wxDouble endAngle, bool clockwise); void AddArc(const wxPoint2DDouble& c, wxDouble r, - wxDouble startAngle, - wxDouble endAngle, - bool clockwise); - //@} + wxDouble startAngle, wxDouble endAngle, bool clockwise); /** - Appends a an arc to two tangents connecting (current) to (x1,y1) and (x1,y1) to - (x2,y2), also a straight line from (current) to (x1,y1). + Appends a an arc to two tangents connecting (current) to (@a x1,@a y1) + and (@a x1,@a y1) to (@a x2,@a y2), also a straight line from (current) + to (@a x1,@a y1). */ virtual void AddArcToPoint(wxDouble x1, wxDouble y1, wxDouble x2, wxDouble y2, wxDouble r); /** - Appends a circle around (x,y) with radius r as a new closed subpath. + Appends a circle around (@a x,@a y) with radius @a r as a new closed + subpath. */ virtual void AddCircle(wxDouble x, wxDouble y, wxDouble r); - //@{ /** - + Adds a cubic bezier curve from the current point, using two control + points and an end point. + */ + void AddCurveToPoint(wxDouble cx1, wxDouble cy1, + wxDouble cx2, wxDouble cy2, + wxDouble x, wxDouble y); + /** + Adds a cubic bezier curve from the current point, using two control + points and an end point. */ - void AddCurveToPoint(wxDouble cx1, wxDouble cy1, wxDouble cx2, - wxDouble cy2, - wxDouble x, - wxDouble y); void AddCurveToPoint(const wxPoint2DDouble& c1, const wxPoint2DDouble& c2, const wxPoint2DDouble& e); - //@} /** Appends an ellipse fitting into the passed in rectangle. */ virtual void AddEllipse(wxDouble x, wxDouble y, wxDouble w, wxDouble h); - //@{ /** - + Adds a straight line from the current point to (@a x,@a y). + */ + virtual void AddLineToPoint(wxDouble x, wxDouble y); + /** + Adds a straight line from the current point to @a p. */ - void AddLineToPoint(wxDouble x, wxDouble y); void AddLineToPoint(const wxPoint2DDouble& p); - //@} /** Adds another path. @@ -77,11 +84,11 @@ public: virtual void AddPath(const wxGraphicsPath& path); /** - Adds a quadratic Bezier curve from the current point, using a control point and - an end point. + Adds a quadratic bezier curve from the current point, using a control + point and an end point. */ - virtual void AddQuadCurveToPoint(wxDouble cx, wxDouble cy, wxDouble x, - wxDouble y); + virtual void AddQuadCurveToPoint(wxDouble cx, wxDouble cy, + wxDouble x, wxDouble y); /** Appends a rectangle as a new closed subpath. @@ -99,46 +106,52 @@ public: */ virtual void CloseSubpath(); - //@{ /** - Returns @true if the point is within the path. + @return @true if the point is within the path. */ bool Contains(const wxPoint2DDouble& c, int fillStyle = wxODDEVEN_RULE) const; - const bool Contains(wxDouble x, wxDouble y, - int fillStyle = wxODDEVEN_RULE) const; - //@} + /** + @return @true if the point is within the path. + */ + virtual bool Contains(wxDouble x, wxDouble y, + int fillStyle = wxODDEVEN_RULE) const; - //@{ /** - Gets the bounding box enclosing all points (possibly including control points). + Gets the bounding box enclosing all points (possibly including control + points). */ wxRect2DDouble GetBox() const; - const void GetBox(wxDouble* x, wxDouble* y, wxDouble* w, - wxDouble* h) const; - //@} + /** + Gets the bounding box enclosing all points (possibly including control + points). + */ + virtual void GetBox(wxDouble* x, wxDouble* y, + wxDouble* w, wxDouble* h) const; - //@{ /** Gets the last point of the current path, (0,0) if not yet set. */ - void GetCurrentPoint(wxDouble* x, wxDouble* y) const; - const wxPoint2DDouble GetCurrentPoint() const; - //@} + virtual void GetCurrentPoint(wxDouble* x, wxDouble* y) const; + /** + Gets the last point of the current path, (0,0) if not yet set. + */ + wxPoint2DDouble GetCurrentPoint() const; /** - Returns the native path (CGPathRef for Core Graphics, Path pointer for GDIPlus - and a cairo_path_t pointer for cairo). + Returns the native path (CGPathRef for Core Graphics, Path pointer for + GDIPlus and a cairo_path_t pointer for cairo). */ virtual void* GetNativePath() const; - //@{ /** - Begins a new subpath at (x,y) + Begins a new subpath at (@a x,@a y). + */ + virtual void MoveToPoint(wxDouble x, wxDouble y); + /** + Begins a new subpath at @a p. */ - void MoveToPoint(wxDouble x, wxDouble y); void MoveToPoint(const wxPoint2DDouble& p); - //@} /** Transforms each point of this path by the matrix. @@ -146,9 +159,9 @@ public: virtual void Transform(const wxGraphicsMatrix& matrix); /** - Gives back the native path returned by GetNativePath() because there might be - some deallocations necessary (eg on cairo the native path returned by - GetNativePath is newly allocated each time). + Gives back the native path returned by GetNativePath() because there + might be some deallocations necessary (e.g. on cairo the native path + returned by GetNativePath() is newly allocated each time). */ virtual void UnGetNativePath(void* p) const; }; @@ -162,7 +175,7 @@ public: allows reference counting. Not instantiated by user code. @library{wxcore} - @category{FIXME} + @category{gdi} @see wxGraphicsBrush, wxGraphicsPen, wxGraphicsMatrix, wxGraphicsPath */ @@ -170,13 +183,13 @@ class wxGraphicsObject : public wxObject { public: /** - Returns the renderer that was used to create this instance, or @NULL if it has - not been initialized yet + Returns the renderer that was used to create this instance, or @NULL + if it has not been initialized yet. */ wxGraphicsRenderer* GetRenderer() const; /** - Is this object valid (@false) or still empty (@true)? + @return @false if this object is valid, otherwise returns @true. */ bool IsNull() const; }; @@ -196,10 +209,10 @@ public: { // Create paint DC wxPaintDC dc(this); - + // Create graphics context from it wxGraphicsContext *gc = wxGraphicsContext::Create( dc ); - + if (gc) { // make a path that contains a circle and some lines @@ -212,9 +225,9 @@ public: path.AddLineToPoint(50.0, 100.0 ); path.CloseSubpath(); path.AddRectangle(25.0, 25.0, 50.0, 50.0); - + gc->StrokePath(path); - + delete gc; } } @@ -222,7 +235,7 @@ public: @library{wxcore} - @category{FIXME} + @category{gdi,dc} @see wxGraphicsRenderer::CreateContext(), wxGCDC, wxDC */ @@ -235,21 +248,21 @@ public: @see wxGraphicsRenderer::CreateContext() */ static wxGraphicsContext* Create( wxWindow* window ) ; - + /** Creates a wxGraphicsContext from a wxWindowDC @see wxGraphicsRenderer::CreateContext() */ static wxGraphicsContext* Create( const wxWindowDC& dc) ; - + /** Creates a wxGraphicsContext from a wxMemoryDC @see wxGraphicsRenderer::CreateContext() */ static wxGraphicsContext * Create( const wxMemoryDC& dc) ; - + /** Creates a wxGraphicsContext from a wxPrinterDC. Under GTK+, this will only work when using the GtkPrint @@ -527,17 +540,17 @@ public: Creates a wxGraphicsContext from a wxWindow. */ virtual wxGraphicsContext* CreateContext(wxWindow* window) = 0; - + /** Creates a wxGraphicsContext from a wxWindowDC */ virtual wxGraphicsContext * CreateContext( const wxWindowDC& dc) = 0 ; - + /** Creates a wxGraphicsContext from a wxMemoryDC */ virtual wxGraphicsContext * CreateContext( const wxMemoryDC& dc) = 0 ; - + /** Creates a wxGraphicsContext from a wxPrinterDC */ @@ -756,4 +769,3 @@ public: */ virtual void Translate(wxDouble dx, wxDouble dy); }; -