papyrus logo

Quick Start Guide to Papyrus

This is intended to be a very succinct guide to papyrus, and is not intended as a general tutorial.

Concept #1: The canvas

Papyrus is structured around the concept of a model-view separation. In the Papyrus library, there are no views... only models, including Papyrus::Canvas itself. (Read on to find out where the views are)

Concept #2: Drawables

Drawables are added to a Papyrus::Canvas. Most drawables inherit from Papyrus::Shape.

Concept #3: Rendering (or moving from models to eye candy)

A papyrus model is made 'tangible' by rendering into a cairo context. Papyrus::Canvas and most other objects in Papyrus inherit from Papyrus::Renderable which has a render() method. Thus, rendering into a cairomm context is the way to view a Papyrus::Canvas.

Concept #4: Cairo Contexts

In cairo, a context is created from a surface. Cairo supports numerous surfaces including:

This quick-start won't go into the specifics of cairomm surfaces (I'll leave that to the cairomm library), but suffice it to say that a Papyrus::Renderable (including the Papyrus::Canvas) is rendered into a cairomm context which results in drawing a papyrus object to any of the above surfaces.

Concept #5: Viewports

PapyrusGtk::Viewport is a Gtkmm widget that serves as a view on a Papyrus::Canvas model, and creates a cairomm context 'behind the scenes'. This provides a viewport into the world of the canvas model you have created.

Viewports are only one of many ways to display a Papyrus model in a Gtkmm widget.

Concepts #6, #7 and #8: Smart Pointers, pointer and create()

An early design decision was made to focus on the use of smart pointers as defined in the ANSI C++ committee's tr1 (Technical Report 1), which as of this writing has been accepted by the committee and recommended to ISO for incorporation as the first revision to the C++ standard. A reference implementation can be found in the boost library or in the std::tr1 namespace of gcc 4.0 or greater.

Two key concepts are the pointer typedef and the create method defined in each Papyrus class.

The pointer typedef is defined within each class and is typedefed to a smart pointer to that class. Thus, Papyrus::Rectangle::pointer is a smart pointer to a rectangle, and Papyrus::Circle::pointer is a smart pointer to a circle.

Each class also has static create() methods with parameters that are identical to the class' constructors. The create() method returns a smart pointer to that object, similar to the way the new operator returns a pointer. Since the create() method is static, you do not need an instance of the class to call it; Classname::create() is sufficient.

Naturally, the smart pointer returned from create() can be assigned to the class' pointer type, which allows you to use a syntax such as:

 Classname::pointer my_variable = Classname::create(); 

Putting it all together

Create a PapyrusGtk viewport

 PapyrusGtk::Viewport my_viewport; 

Set the viewport to an initial size of 200 x 200 and center the view

 my_viewport.canvas->set_size(200, 200);
 my_viewport.set_scroll_point( PapyrusGtk::SCROLL_TO_CENTER );

Create a rectangle of length 100 and width 50

 Papyrus::Rectangle::pointer my_rectangle = Papyrus::Rectangle::create(100, 50); 

Color your rectangle red and make it slightly transparent by setting alpha to 0.9

 my_rectangle->set_fill( Papyrus::RGBA(1.0, 0.0, 0.0, 0.9) ); 

Add your red (and slightly transparent) rectangle to the viewport's canvas

 my_viewport.canvas()->add( my_rectangle ); 

At this point you have a Gtkmm widget named my_viewport that you can incorporate into your program as you would any other Gtkmm widget by adding it to a container, window, etc.

 Gtk::Window my_window;
 my_window.add( my_viewport );

Since this isn't a tutorial on Gtkmm (they have a fine one here) I'll bring this quick start to an end.

Generated on Fri Apr 16 12:41:04 2010 for papyrus by doxygen 1.6.1