Protocols

The PangoAnalysis structure stores information about the properties of a segment of text.

The AnalysisProtocol protocol exposes the methods and properties of an underlying PangoAnalysis instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Analysis. Alternatively, use AnalysisRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoAttrClass structure stores the type and operations for a particular type of attribute.

The functions in this structure should not be called directly. Instead, one should use the wrapper functions provided for PangoAttribute.

The AttrClassProtocol protocol exposes the methods and properties of an underlying PangoAttrClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see AttrClass. Alternatively, use AttrClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoAttrColor structure is used to represent attributes that are colors.

The AttrColorProtocol protocol exposes the methods and properties of an underlying PangoAttrColor instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see AttrColor. Alternatively, use AttrColorRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoAttrFloat structure is used to represent attributes with a float or double value.

The AttrFloatProtocol protocol exposes the methods and properties of an underlying PangoAttrFloat instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see AttrFloat. Alternatively, use AttrFloatRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoAttrFontDesc structure is used to store an attribute that sets all aspects of the font description at once.

The AttrFontDescProtocol protocol exposes the methods and properties of an underlying PangoAttrFontDesc instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see AttrFontDesc. Alternatively, use AttrFontDescRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoAttrFontFeatures structure is used to represent OpenType font features as an attribute.

The AttrFontFeaturesProtocol protocol exposes the methods and properties of an underlying PangoAttrFontFeatures instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see AttrFontFeatures. Alternatively, use AttrFontFeaturesRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoAttrInt structure is used to represent attributes with an integer or enumeration value.

The AttrIntProtocol protocol exposes the methods and properties of an underlying PangoAttrInt instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see AttrInt. Alternatively, use AttrIntRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoAttrIterator is used to iterate through a PangoAttrList.

A new iterator is created with [methodPango.AttrList.get_iterator]. Once the iterator is created, it can be advanced through the style changes in the text using [methodPango.AttrIterator.next]. At each style change, the range of the current style segment and the attributes currently in effect can be queried.

The AttrIteratorProtocol protocol exposes the methods and properties of an underlying PangoAttrIterator instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see AttrIterator. Alternatively, use AttrIteratorRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoAttrLanguage structure is used to represent attributes that are languages.

The AttrLanguageProtocol protocol exposes the methods and properties of an underlying PangoAttrLanguage instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see AttrLanguage. Alternatively, use AttrLanguageRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoAttrList represents a list of attributes that apply to a section of text.

The attributes in a PangoAttrList are, in general, allowed to overlap in an arbitrary fashion. However, if the attributes are manipulated only through [methodPango.AttrList.change], the overlap between properties will meet stricter criteria.

Since the PangoAttrList structure is stored as a linear list, it is not suitable for storing attributes for large amounts of text. In general, you should not use a single PangoAttrList for more than one paragraph of text.

The AttrListProtocol protocol exposes the methods and properties of an underlying PangoAttrList instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see AttrList. Alternatively, use AttrListRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoAttrShape structure is used to represent attributes which impose shape restrictions.

The AttrShapeProtocol protocol exposes the methods and properties of an underlying PangoAttrShape instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see AttrShape. Alternatively, use AttrShapeRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoAttrSize structure is used to represent attributes which set font size.

The AttrSizeProtocol protocol exposes the methods and properties of an underlying PangoAttrSize instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see AttrSize. Alternatively, use AttrSizeRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoAttrString structure is used to represent attributes with a string value.

The AttrStringProtocol protocol exposes the methods and properties of an underlying PangoAttrString instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see AttrString. Alternatively, use AttrStringRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoAttribute structure represents the common portions of all attributes.

Particular types of attributes include this structure as their initial portion. The common portion of the attribute holds the range to which the value in the type-specific part of the attribute applies and should be initialized using [methodPango.Attribute.init]. By default, an attribute will have an all-inclusive range of [0,G_MAXUINT].

The AttributeProtocol protocol exposes the methods and properties of an underlying PangoAttribute instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Attribute. Alternatively, use AttributeRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoContext stores global information used to control the itemization process.

The information stored by PangoContext includes the fontmap used to look up fonts, and default values such as the default language, default gravity, or default font.

To obtain a PangoContext, use [methodPango.FontMap.create_context].

The ContextProtocol protocol exposes the methods and properties of an underlying PangoContext instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Context. Alternatively, use ContextRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoCoverage structure is a map from Unicode characters to [enumPango.CoverageLevel] values.

It is often necessary in Pango to determine if a particular font can represent a particular character, and also how well it can represent that character. The PangoCoverage is a data structure that is used to represent that information. It is an opaque structure with no public fields.

The CoverageProtocol protocol exposes the methods and properties of an underlying PangoCoverage instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Coverage. Alternatively, use CoverageRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoColor structure is used to represent a color in an uncalibrated RGB color-space.

The ColorProtocol protocol exposes the methods and properties of an underlying PangoColor instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Color. Alternatively, use ColorRef as a lighweight, unowned reference if you already have an instance you just want to use.

The ContextClassProtocol protocol exposes the methods and properties of an underlying PangoContextClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see ContextClass. Alternatively, use ContextClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoFont is used to represent a font in a rendering-system-independent manner.

The FontProtocol protocol exposes the methods and properties of an underlying PangoFont instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Font. Alternatively, use FontRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoFontFace is used to represent a group of fonts with the same family, slant, weight, and width, but varying sizes.

The FontFaceProtocol protocol exposes the methods and properties of an underlying PangoFontFace instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FontFace. Alternatively, use FontFaceRef as a lighweight, unowned reference if you already have an instance you just want to use.

The FontClassProtocol protocol exposes the methods and properties of an underlying PangoFontClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FontClass. Alternatively, use FontClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoFontFamily is used to represent a family of related font faces.

The font faces in a family share a common design, but differ in slant, weight, width or other aspects.

The FontFamilyProtocol protocol exposes the methods and properties of an underlying PangoFontFamily instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FontFamily. Alternatively, use FontFamilyRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoFontMap represents the set of fonts available for a particular rendering system.

This is a virtual object with implementations being specific to particular rendering systems.

The FontMapProtocol protocol exposes the methods and properties of an underlying PangoFontMap instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FontMap. Alternatively, use FontMapRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoFontset represents a set of PangoFont to use when rendering text.

A PangoFontset is the result of resolving a PangoFontDescription against a particular PangoContext. It has operations for finding the component font for a particular Unicode character, and for finding a composite set of metrics for the entire fontset.

The FontsetProtocol protocol exposes the methods and properties of an underlying PangoFontset instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Fontset. Alternatively, use FontsetRef as a lighweight, unowned reference if you already have an instance you just want to use.

PangoFontsetSimple is a implementation of the abstract PangoFontset base class as an array of fonts.

When creating a PangoFontsetSimple, you have to provide the array of fonts that make up the fontset.

The FontsetSimpleProtocol protocol exposes the methods and properties of an underlying PangoFontsetSimple instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FontsetSimple. Alternatively, use FontsetSimpleRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoFontDescription describes a font in an implementation-independent manner.

PangoFontDescription structures are used both to list what fonts are available on the system and also for specifying the characteristics of a font to load.

The FontDescriptionProtocol protocol exposes the methods and properties of an underlying PangoFontDescription instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FontDescription. Alternatively, use FontDescriptionRef as a lighweight, unowned reference if you already have an instance you just want to use.

The FontFaceClassProtocol protocol exposes the methods and properties of an underlying PangoFontFaceClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FontFaceClass. Alternatively, use FontFaceClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

The FontFamilyClassProtocol protocol exposes the methods and properties of an underlying PangoFontFamilyClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FontFamilyClass. Alternatively, use FontFamilyClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoFontMapClass structure holds the virtual functions for a particular PangoFontMap implementation.

The FontMapClassProtocol protocol exposes the methods and properties of an underlying PangoFontMapClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FontMapClass. Alternatively, use FontMapClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoFontMetrics structure holds the overall metric information for a font.

The information in a PangoFontMetrics structure may be restricted to a script. The fields of this structure are private to implementations of a font backend. See the documentation of the corresponding getters for documentation of their meaning.

For an overview of the most important metrics, see:

<picture> <source srcset=“fontmetrics-dark.png” media=“(prefers-color-scheme: dark)”> <img alt=“Font metrics” src=“fontmetrics-light.png”> </picture>

The FontMetricsProtocol protocol exposes the methods and properties of an underlying PangoFontMetrics instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FontMetrics. Alternatively, use FontMetricsRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoFontsetClass structure holds the virtual functions for a particular PangoFontset implementation.

The FontsetClassProtocol protocol exposes the methods and properties of an underlying PangoFontsetClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FontsetClass. Alternatively, use FontsetClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

The FontsetSimpleClassProtocol protocol exposes the methods and properties of an underlying PangoFontsetSimpleClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FontsetSimpleClass. Alternatively, use FontsetSimpleClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoGlyphGeometry structure contains width and positioning information for a single glyph.

Note that width is not guaranteed to be the same as the glyph extents. Kerning and other positioning applied during shaping will affect both the width and the x_offset for the glyphs in the glyph string that results from shaping.

The information in this struct is intended for rendering the glyphs, as follows:

1. Assume the current point is (x, y)
2. Render the current glyph at (x + x_offset, y + y_offset),
3. Advance the current point to (x + width, y)
4. Render the next glyph

The GlyphGeometryProtocol protocol exposes the methods and properties of an underlying PangoGlyphGeometry instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see GlyphGeometry. Alternatively, use GlyphGeometryRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoGlyphInfo structure represents a single glyph with positioning information and visual attributes.

The GlyphInfoProtocol protocol exposes the methods and properties of an underlying PangoGlyphInfo instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see GlyphInfo. Alternatively, use GlyphInfoRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoGlyphItem is a pair of a PangoItem and the glyphs resulting from shaping the items text.

As an example of the usage of PangoGlyphItem, the results of shaping text with PangoLayout is a list of PangoLayoutLine, each of which contains a list of PangoGlyphItem.

The GlyphItemProtocol protocol exposes the methods and properties of an underlying PangoGlyphItem instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see GlyphItem. Alternatively, use GlyphItemRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoGlyphItemIter is an iterator over the clusters in a PangoGlyphItem.

The forward direction of the iterator is the logical direction of text. That is, with increasing start_index and start_char values. If glyph_item is right-to-left (that is, if glyph_item->item->analysis.level is odd), then start_glyph decreases as the iterator moves forward. Moreover, in right-to-left cases, start_glyph is greater than end_glyph.

An iterator should be initialized using either pango_glyph_item_iter_init_start() or pango_glyph_item_iter_init_end(), for forward and backward iteration respectively, and walked over using any desired mixture of pango_glyph_item_iter_next_cluster() and pango_glyph_item_iter_prev_cluster().

A common idiom for doing a forward iteration over the clusters is:

PangoGlyphItemIter cluster_iter;
gboolean have_cluster;

for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter,
                                                      glyph_item, text);
     have_cluster;
     have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter))
{
  ...
}

Note that text is the start of the text for layout, which is then indexed by glyph_item->item->offset to get to the text of glyph_item. The start_index and end_index values can directly index into text. The start_glyph, end_glyph, start_char, and end_char values however are zero-based for the glyph_item. For each cluster, the item pointed at by the start variables is included in the cluster while the one pointed at by end variables is not.

None of the members of a PangoGlyphItemIter should be modified manually.

The GlyphItemIterProtocol protocol exposes the methods and properties of an underlying PangoGlyphItemIter instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see GlyphItemIter. Alternatively, use GlyphItemIterRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoGlyphString is used to store strings of glyphs with geometry and visual attribute information.

The storage for the glyph information is owned by the structure which simplifies memory management.

The GlyphStringProtocol protocol exposes the methods and properties of an underlying PangoGlyphString instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see GlyphString. Alternatively, use GlyphStringRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoGlyphVisAttr structure communicates information between the shaping and rendering phases.

Currently, it contains cluster start and color information. More attributes may be added in the future.

Clusters are stored in visual order, within the cluster, glyphs are always ordered in logical order, since visual order is meaningless; that is, in Arabic text, accent glyphs follow the glyphs for the base character.

The GlyphVisAttrProtocol protocol exposes the methods and properties of an underlying PangoGlyphVisAttr instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see GlyphVisAttr. Alternatively, use GlyphVisAttrRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoItem structure stores information about a segment of text.

You typically obtain PangoItems by itemizing a piece of text with [funcitemize].

The ItemProtocol protocol exposes the methods and properties of an underlying PangoItem instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Item. Alternatively, use ItemRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoLayout structure represents an entire paragraph of text.

While complete access to the layout capabilities of Pango is provided using the detailed interfaces for itemization and shaping, using that functionality directly involves writing a fairly large amount of code. PangoLayout provides a high-level driver for formatting entire paragraphs of text at once. This includes paragraph-level functionality such as line breaking, justification, alignment and ellipsization.

A PangoLayout is initialized with a PangoContext, UTF-8 string and set of attributes for that string. Once that is done, the set of formatted lines can be extracted from the object, the layout can be rendered, and conversion between logical character positions within the layout’s text, and the physical position of the resulting glyphs can be made.

There are a number of parameters to adjust the formatting of a PangoLayout. The following image shows adjustable parameters (on the left) and font metrics (on the right):

<picture> <source srcset=“layout-dark.png” media=“(prefers-color-scheme: dark)”> <img alt=“Pango Layout Parameters” src=“layout-light.png”> </picture>

The following images demonstrate the effect of alignment and justification on the layout of text:

It is possible, as well, to ignore the 2-D setup, and simply treat the results of a PangoLayout as a list of lines.

The LayoutProtocol protocol exposes the methods and properties of an underlying PangoLayout instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Layout. Alternatively, use LayoutRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoLanguage structure is used to represent a language.

PangoLanguage pointers can be efficiently copied and compared with each other.

The LanguageProtocol protocol exposes the methods and properties of an underlying PangoLanguage instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Language. Alternatively, use LanguageRef as a lighweight, unowned reference if you already have an instance you just want to use.

The LayoutClassProtocol protocol exposes the methods and properties of an underlying PangoLayoutClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see LayoutClass. Alternatively, use LayoutClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoLayoutIter can be used to iterate over the visual extents of a PangoLayout.

To obtain a PangoLayoutIter, use [methodPango.Layout.get_iter].

The PangoLayoutIter structure is opaque, and has no user-visible fields.

The LayoutIterProtocol protocol exposes the methods and properties of an underlying PangoLayoutIter instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see LayoutIter. Alternatively, use LayoutIterRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoLayoutLine represents one of the lines resulting from laying out a paragraph via PangoLayout.

PangoLayoutLine structures are obtained by calling [methodPango.Layout.get_line] and are only valid until the text, attributes, or settings of the parent PangoLayout are modified.

The LayoutLineProtocol protocol exposes the methods and properties of an underlying PangoLayoutLine instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see LayoutLine. Alternatively, use LayoutLineRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoLogAttr structure stores information about the attributes of a single character.

The LogAttrProtocol protocol exposes the methods and properties of an underlying PangoLogAttr instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see LogAttr. Alternatively, use LogAttrRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoMatrix specifies a transformation between user-space and device coordinates.

The transformation is given by

x_device = x_user * matrix->xx + y_user * matrix->xy + matrix->x0;
y_device = x_user * matrix->yx + y_user * matrix->yy + matrix->y0;

The MatrixProtocol protocol exposes the methods and properties of an underlying PangoMatrix instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Matrix. Alternatively, use MatrixRef as a lighweight, unowned reference if you already have an instance you just want to use.

PangoRenderer is a base class for objects that can render text provided as PangoGlyphString or PangoLayout.

By subclassing PangoRenderer and overriding operations such as draw_glyphs and draw_rectangle, renderers for particular font backends and destinations can be created.

The RendererProtocol protocol exposes the methods and properties of an underlying PangoRenderer instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Renderer. Alternatively, use RendererRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PangoRectangle structure represents a rectangle.

PangoRectangle is frequently used to represent the logical or ink extents of a single glyph or section of text. (See, for instance, [methodPango.Font.get_glyph_extents].)

The RectangleProtocol protocol exposes the methods and properties of an underlying PangoRectangle instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Rectangle. Alternatively, use RectangleRef as a lighweight, unowned reference if you already have an instance you just want to use.

Class structure for PangoRenderer.

The following vfuncs take user space coordinates in Pango units and have default implementations:

• draw_glyphs
• draw_rectangle
• draw_error_underline
• draw_shape
• draw_glyph_item

The default draw_shape implementation draws nothing.

The following vfuncs take device space coordinates as doubles and must be implemented:

• draw_trapezoid
• draw_glyph

The RendererClassProtocol protocol exposes the methods and properties of an underlying PangoRendererClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see RendererClass. Alternatively, use RendererClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoScriptIter is used to iterate through a string and identify ranges in different scripts.

The ScriptIterProtocol protocol exposes the methods and properties of an underlying PangoScriptIter instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see ScriptIter. Alternatively, use ScriptIterRef as a lighweight, unowned reference if you already have an instance you just want to use.

A PangoTabArray contains an array of tab stops.

PangoTabArray can be used to set tab stops in a PangoLayout. Each tab stop has an alignment, a position, and optionally a character to use as decimal point.

The TabArrayProtocol protocol exposes the methods and properties of an underlying PangoTabArray instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see TabArray. Alternatively, use TabArrayRef as a lighweight, unowned reference if you already have an instance you just want to use.