### Start Freeform Path Element

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/freeform.html

Creates and returns a new `a:path` XML element, adding it to the provided shape element `sp`. The path is initialized with a `moveTo` operation at the shape's starting point.

```python
def _start_path(self, sp):
    """Return a newly created `a:path` element added to *sp*.

    The returned `a:path` element has an `a:moveTo` element representing
    the shape starting point as its only child.
    """
    path = sp.add_path(w=self._dx, h=self._dy)
    path.add_moveTo(*self._local_to_shape(self._start_x, self._start_y))
    return path
```

--------------------------------

### Autofit Textbox XML Example

Source: https://daobook.github.io/python-pptx/dev/analysis/txt-autofit-text.html

XML for a text box demonstrating auto-reduced font size and text wrapping.

```xml
<p:txBody>
  <a:bodyPr wrap="square" rtlCol="0">
    <a:normAutofit fontScale="55000" lnSpcReduction="20000"/>
  </a:bodyPr>
  <a:lstStyle/>
  <a:p>
    <a:r>
      <a:rPr lang="en-US" dirty="0" smtClean="0"/>
      <a:t>The art and craft of designing typefaces is called type design.
           Designers of typefaces are called type designers and are often
           employed by type foundries. In digital typography, type
           designers are sometimes also called font developers or font
           designers.</a:t>
    </a:r>
    <a:endParaRPr lang="en-US" dirty="0"/>
  </a:p>
</p:txBody>

```

--------------------------------

### ImagePart.new() Example

Source: https://daobook.github.io/python-pptx/_modules/pptx/parts/image.html

Demonstrates creating a new ImagePart instance from an Image object. This is used internally by the library to add images to a presentation package.

```python
ImagePart.new(package, image)
```

--------------------------------

### Table as GraphicFrame Example

Source: https://daobook.github.io/python-pptx/community/updates.html

Illustrates the change where a table is now treated as a graphical object within a GraphicFrame, not a shape itself.

```python
table = shapes.add_table(...)

# becomes

graphic_frame = shapes.add_table(...)
table = graphic_frame.table
```

--------------------------------

### Create a New FreeformBuilder

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/freeform.html

Instantiate a FreeformBuilder to begin defining a freeform shape. The starting point and scaling factors for local coordinates are provided.

```python
from pptx.util import Inches

shapes = slide.shapes

# Create a freeform shape builder starting at (1.0, 1.0) inches
# and scaled to the slide's width and height.
fb = FreeformBuilder.new(shapes, Inches(1), Inches(1), slide.width, slide.height)
```

--------------------------------

### Moving Connector Begin Point to Connection Point

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/connector.html

Adjusts the starting coordinates of the connector to align with a specific connection point on a target shape.

```python
def _move_begin_to_cxn(self, shape, cxn_pt_idx):
    """
    Move the begin point of this connector to coordinates of the
    connection point of *shape* specified by *cxn_pt_idx*.
    """
    x, y, cx, cy = shape.left, shape.top, shape.width, shape.height
    self.begin_x, self.begin_y = {
        0: (int(x + cx / 2), y),
        1: (x, int(y + cy / 2)),
        2: (int(x + cx / 2), y + cy),
        3: (x + cx, int(y + cy / 2)),
    }[cxn_pt_idx]
```

--------------------------------

### Set and Get Font Typeface

Source: https://daobook.github.io/python-pptx/dev/analysis/txt-font-typeface.html

Demonstrates how to set a font's typeface to 'Verdana' and then retrieve it. Asserts that the font object is of the correct type.

```python
assert isinstance(font, pptx.text.Font)
>>> font.name
None
>>> font.name = 'Verdana'
>>> font.name
'Verdana'
```

--------------------------------

### build_freeform

Source: https://daobook.github.io/python-pptx/api/shapes.html

Returns a FreeformBuilder object to define a freeform shape. Starting position and scale can be specified.

```APIDOC
## `build_freeform`

### Description
Returns a `FreeformBuilder` object that can be used to specify a freeform shape. Optional starting position and scale arguments can be provided.

### Method
`build_freeform(_start_x =0_, _start_y =0_, _scale =1.0_)

### Parameters
- `_start_x_` (int, optional): The starting x-coordinate in local coordinates. Defaults to 0.
- `_start_y_` (int, optional): The starting y-coordinate in local coordinates. Defaults to 0.
- `_scale_` (float or tuple, optional): The scale of local coordinates proportional to slide coordinates (EMU). Can be a single float for uniform scaling or a tuple (X_scale, Y_scale) for non-uniform scaling. Defaults to 1.0.

### Returns
- `FreeformBuilder`: A `FreeformBuilder` object for defining a freeform shape.
```

--------------------------------

### Get Video Object

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/shapetree.html

Returns a Video object representing the movie file. It can be created from a file path or a file-like object.

```python
@lazyproperty
    def _video(self):
        """Return a |Video| object containing the movie file."""
        return Video.from_path_or_file_like(self._movie_file, self._mime_type)
```

--------------------------------

### ST_GeomGuideName Simple Type

Source: https://daobook.github.io/python-pptx/dev/analysis/shp-preset-geom.html

Defines a simple token type for geometry guide names.

```xml
<xsd:simpleType name="ST_GeomGuideName">
  <xsd:restriction base="xsd:token"/>
</xsd:simpleType>
```

--------------------------------

### Example of Adding an Embedded XLSX Shape

Source: https://daobook.github.io/python-pptx/dev/analysis/shp-ole-object.html

An example demonstrating how to add an OLE object, specifically an Excel file, to a slide's shapes. Ensure 'shapes', 'slide', 'left', 'top', 'width', 'height', and 'file_name' are defined in your context.

```python
shapes = slide.shapes
embedded_xlsx_shape = shapes.AddOLEObject(left, top, width, height, file_name)
```

--------------------------------

### Get Poster Frame Image File

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/shapetree.html

Provides the image file for the video placeholder. If no poster frame file is specified, it returns the default 'media loudspeaker' image bytes.

```python
@lazyproperty
    def _poster_frame_image_file(self):
        """Return the image file for video placeholder image.

        If no poster frame file is provided, the default "media loudspeaker"
        image is used.
        """
        poster_frame_file = self._poster_frame_file
        if poster_frame_file is None:
            return BytesIO(SPEAKER_IMAGE_BYTES)
        return poster_frame_file
```

--------------------------------

### Getting and Setting Shape Name

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/base.html

Read or write the name of the shape, e.g., 'Picture 7'.

```python
from pptx.shapes.base import BaseShape

# Assuming 'shape' is an instance of a class inheriting from BaseShape
shape_name = shape.name

shape.name = 'My Custom Shape Name'
```

--------------------------------

### Getting Layout Placeholder by Index

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/shapetree.html

Retrieves the first placeholder shape with a matching index from a collection of layout placeholders. Returns a default value if no match is found.

```python
    def get(self, idx, default=None):
        """
        Return the first placeholder shape with matching *idx* value, or
        *default* if not found.
        """
        for placeholder in self:
            if placeholder.element.ph_idx == idx:
                return placeholder
        return default
```

--------------------------------

### Setting Font Size with Points

Source: https://daobook.github.io/python-pptx/api/text.html

Demonstrates how to set the font size using the `Pt` class for convenient point specification and how to access the size in English Metric Units (EMU) and points.

```python
>> font.size = Pt(24)
>> font.size
304800
>> font.size.pt
24.0
```

--------------------------------

### Get Slide Part

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/shapetree.html

Returns the SlidePart object for the slide containing this movie.

```python
@property
    def _slide_part(self):
        """Return SlidePart object for slide containing this movie."""
        return self._shapes.part
```

--------------------------------

### ST_GeomGuideFormula Simple Type

Source: https://daobook.github.io/python-pptx/dev/analysis/shp-preset-geom.html

Defines a simple string type for geometry guide formulas.

```xml
<xsd:simpleType name="ST_GeomGuideFormula">
  <xsd:restriction base="xsd:string"/>
</xsd:simpleType>
```

--------------------------------

### Get New p:pic Element

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/shapetree.html

Constructs and returns the new p:pic element, referencing the video, its media, and poster frame using their respective rIds and including positioning information.

```python
@lazyproperty
    def _pic(self):
        """Return the new `p:pic` element referencing the video."""
        return CT_Picture.new_video_pic(
            self._shape_id,
            self._shape_name,
            self._video_rId,
            self._media_rId,
            self._poster_frame_rId,
            self._x,
            self._y,
            self._cx,
            self._cy,
        )
```

--------------------------------

### Connecting a Connector's Begin Point

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/connector.html

Establishes a connection from the beginning of this connector to a specified connection point on another shape.

```python
def _connect_begin_to(self, shape, cxn_pt_idx):
    """
    Add or update a stCxn element for this connector that connects its
    begin point to the connection point of *shape* specified by
    *cxn_pt_idx*.
    """
    cNvCxnSpPr = self._element.nvCxnSpPr.cNvCxnSpPr
    stCxn = cNvCxnSpPr.get_or_add_stCxn()
    stCxn.id = shape.shape_id
    stCxn.idx = cxn_pt_idx
```

--------------------------------

### CT_GeomGuide Complex Type

Source: https://daobook.github.io/python-pptx/dev/analysis/shp-preset-geom.html

Represents a single geometry guide with a required name and formula.

```xml
<xsd:complexType name="CT_GeomGuide">
  <xsd:attribute name="name" type="ST_GeomGuideName"    use="required"/>
  <xsd:attribute name="fmla" type="ST_GeomGuideFormula" use="required"/>
</xsd:complexType>
```

--------------------------------

### Getting Fill Type

Source: https://daobook.github.io/python-pptx/_modules/pptx/dml/fill.html

Returns a value from the `MsoFillType` enumeration corresponding to the current fill type.

```python
return self._fill.type
```

--------------------------------

### CT_GeomGuideList Complex Type

Source: https://daobook.github.io/python-pptx/dev/analysis/shp-preset-geom.html

Defines a list of geometry guides, allowing for multiple 'gd' elements.

```xml
<xsd:complexType name="CT_GeomGuideList">
  <xsd:sequence>
    <xsd:element name="gd" type="CT_GeomGuide" minOccurs="0" maxOccurs="unbounded"/>
  </xsd:sequence>
</xsd:complexType>
```

--------------------------------

### Movie Picture Element Creator Initialization

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/shapetree.html

Initializes the movie picture element creator with details about the movie, its dimensions, and optional poster frame image.

```python
def __init__(
        self,
        shapes,
        shape_id,
        movie_file,
        x,
        y,
        cx,
        cy,
        poster_frame_file,
        mime_type,
    ):
        super(_MoviePicElementCreator, self).__init__()
        self._shapes = shapes
        self._shape_id = shape_id
        self._movie_file = movie_file
        self._x, self._y, self._cx, self._cy = x, y, cx, cy
        self._poster_frame_file = poster_frame_file
        self._mime_type = mime_type
```

--------------------------------

### Accessing Placeholder Format

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/base.html

Get a |_PlaceholderFormat| object for placeholder-specific properties. Raises ValueError if the shape is not a placeholder.

```python
from pptx.shapes.base import BaseShape

# Assuming 'shape' is an instance of a class inheriting from BaseShape
try:
    placeholder_format = shape.placeholder_format
except ValueError:
    print('Shape is not a placeholder')
```

--------------------------------

### Initialize FillFormat from Parent Element

Source: https://daobook.github.io/python-pptx/_modules/pptx/dml/fill.html

Creates a FillFormat instance from an element that contains EG_FillProperties. This is useful for accessing and modifying existing fill settings.

```python
fill_format = FillFormat.from_fill_parent(shape.shape_type.spPr)
```

--------------------------------

### Getting and Setting Shape Height

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/base.html

Read or write the height of the shape in English Metric Units (EMUs).

```python
from pptx.shapes.base import BaseShape

# Assuming 'shape' is an instance of a class inheriting from BaseShape
current_height = shape.height

# Set height to 500000 EMUs (approx 2.5 inches)
shape.height = 500000
```

--------------------------------

### Accessing and Setting Theme Color

Source: https://daobook.github.io/python-pptx/_modules/pptx/dml/color.html

Shows how to retrieve the theme color and how to assign a new theme color. Assigning a theme color changes the color type to MSO_COLOR_TYPE.SCHEME.

```python
from pptx.enum.dml import MSO_THEME_COLOR

# Assuming 'shape' is a shape with a fill that has a color property
fill = shape.fill

# Get the theme color
theme_color = fill.fore_color.theme_color

# Set the theme color
fill.fore_color.theme_color = MSO_THEME_COLOR.ACCENT_1
```

--------------------------------

### Run Macro Action

Source: https://daobook.github.io/python-pptx/dev/analysis/shp-hyperlink.html

Specifies a shape to execute a macro using the 'ppaction://macro' action, with the macro name provided as a parameter.

```XML
<p:sp>
  <p:nvSpPr>
    <p:cNvPr id="4" name="Rounded Rectangle 3">
      <a:hlinkClick r:id="" action="ppaction://macro?name=Hello"/>
    </p:cNvPr>
  ...
</p:sp>
```

--------------------------------

### Accessing and Setting RGB Color

Source: https://daobook.github.io/python-pptx/_modules/pptx/dml/color.html

Demonstrates how to get the RGBColor value of a color and how to set it. Setting an RGB color may change the underlying color type and remove any existing brightness adjustments.

```python
from pptx.dml.color import RGBColor

# Assuming 'shape' is a shape with a fill that has a color property
fill = shape.fill

# Get the RGB value
rgb_color = fill.fore_color.rgb

# Set the RGB value
fill.fore_color.rgb = RGBColor(0x12, 0x34, 0x56)
```

--------------------------------

### Accessing Major Gridlines Object

Source: https://daobook.github.io/python-pptx/_modules/pptx/chart/axis.html

Get the MajorGridlines object for an axis, which allows further manipulation of major gridline properties.

```python
from pptx.chart.axis import _BaseAxis

# Assuming 'axis' is an instance of a class inheriting from _BaseAxis
major_gridlines = axis.major_gridlines
```

--------------------------------

### _SolidFill Class

Source: https://daobook.github.io/python-pptx/_modules/pptx/dml/fill.html

Provides access to fill properties such as color for solid fills.

```APIDOC
## _SolidFill Class

### Description
Provides access to fill properties such as color for solid fills.

### Properties
- **fore_color**: Returns |ColorFormat| object controlling fill color.
- **type**: Returns MSO_FILL.SOLID.
```

--------------------------------

### Get Shape Type (Picture)

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/picture.html

Returns the unique integer identifier for this shape, which is always MSO_SHAPE_TYPE.PICTURE for picture shapes.

```python
return MSO_SHAPE_TYPE.PICTURE
```

--------------------------------

### FreeformBuilder.new

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/freeform.html

Creates a new FreeformBuilder object. The initial pen location is specified in local coordinates.

```APIDOC
## FreeformBuilder.new

### Description
Return a new |FreeformBuilder| object. The initial pen location is specified (in local coordinates) by (*start_x*, *start_y*).

### Method
`FreeformBuilder.new(shapes, start_x, start_y, x_scale, y_scale)`

### Parameters
* **shapes**: The shapes collection to add the freeform to.
* **start_x** (int): The x-coordinate of the starting point in local coordinates.
* **start_y** (int): The y-coordinate of the starting point in local coordinates.
* **x_scale**: The x-axis scaling factor.
* **y_scale**: The y-axis scaling factor.

### Returns
A new |FreeformBuilder| object.
```

--------------------------------

### Build Freeform Shape

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/shapetree.html

Initializes a FreeformBuilder object to define a freeform shape. Supports specifying starting position and scaling.

```python
try:
            x_scale, y_scale = scale
        except TypeError:
            x_scale = y_scale = scale

        return FreeformBuilder.new(self, start_x, start_y, x_scale, y_scale)
```

--------------------------------

### Setting Solid Fill

Source: https://daobook.github.io/python-pptx/_modules/pptx/dml/fill.html

Initializes a solid fill object. This enables subsequent assignments to properties like `fore_color` to set the color.

```python
solidFill = self._xPr.get_or_change_to_solidFill()
self._fill = _SolidFill(solidFill)
```

--------------------------------

### Image.from_file() Class Method

Source: https://daobook.github.io/python-pptx/_modules/pptx/parts/image.html

Creates a new immutable Image object from a file. Accepts either a file path (string) or a file-like object.

```python
Image.from_file(image_file)
```

--------------------------------

### Get Slide Title Placeholder

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/shapetree.html

Retrieves the title placeholder shape for the slide. Returns None if the slide does not have a title placeholder.

```python
@property
    def title(self):
        """
        The title placeholder shape on the slide or |None| if the slide has
        no title placeholder.
        """
        for elm in self._spTree.iter_ph_elms():
            if elm.ph_idx == 0:
                return self._shape_factory(elm)
        return None
```

--------------------------------

### Get Shape Index

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/shapetree.html

Returns the index of a given shape within the shape tree. Raises ValueError if the shape is not found.

```python
shape_elms = list(self._element.iter_shape_elms())
return shape_elms.index(shape.element)
```

--------------------------------

### Run Program Hyperlink

Source: https://daobook.github.io/python-pptx/dev/analysis/shp-hyperlink.html

Defines a hyperlink to execute an external program. The Relationship element must be of type 'hyperlink' and 'External', pointing to the program's executable with a 'file://' protocol URL.

```XML
<p:sp>
  <p:nvSpPr>
    <p:cNvPr id="4" name="Rounded Rectangle 3">
      <a:hlinkClick r:id="rId2" action="ppaction://program"/>
    ...
</p:sp>
```

```XML
<Relationship
  Id="rId2"
  Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink"
  Target="file:///C:\\Program%20Files%20(x86)\\Vim\\vim74\\gvim.exe"
  TargetMode="External"/>
```

--------------------------------

### Getting the Number of Shapes

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/shapetree.html

Return the total count of shapes in the collection. Note that group shapes are counted as a single item.

```python
count = len(shapes)
```

--------------------------------

### Get Number of Cells in Row in Python-PPTX

Source: https://daobook.github.io/python-pptx/_modules/pptx/table.html

Supports the `len()` function to retrieve the total number of cells in a table row.

```python
def __len__(self):
    """Supports len() function (e.g. 'len(cells) == 1')."""
    return len(self._tr.tc_lst)
```

--------------------------------

### XML Gradient Fill Specimen 2

Source: https://daobook.github.io/python-pptx/dev/analysis/dml-gradient.html

This XML specimen illustrates a simple gradient fill created using the gradient dialog. It features two gradient stops with modifications to shade, saturation, luminosity, and offset.

```xml
<a:gradFill flip="none" rotWithShape="1">
  <a:gsLst>
    <a:gs pos="0">
      <a:schemeClr val="accent1">
        <a:shade val="51000"/>
        <a:satMod val="130000"/>
      </a:schemeClr>
    </a:gs>
    <a:gs pos="100000">
      <a:schemeClr val="accent1">
        <a:lumMod val="40000"/>
        <a:lumOff val="60000"/>
      </a:schemeClr>
    </a:gs>
  </a:gsLst>
  <a:lin ang="2700000" scaled="0"/>
  <a:tileRect/>
</a:gradFill>
```

--------------------------------

### Open Local File Hyperlink

Source: https://daobook.github.io/python-pptx/dev/analysis/shp-hyperlink.html

Configures a shape to open an arbitrary file on the same computer using the 'ppaction://hlinkfile' action. The target file is specified with a 'file://' protocol URL in the Relationship element.

```XML
<p:sp>
  <p:nvSpPr>
    <p:cNvPr id="7" name="Rounded Rectangle 6">
      <a:hlinkClick r:id="rId2" action="ppaction://hlinkfile"/>
      ...
</p:sp>
```

```XML
<Relationship
  Id="rId2"
  Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink"
  Target="file:///C:\\Install.log"
  TargetMode="External"/>
```

--------------------------------

### Get Category Type for Date Axis

Source: https://daobook.github.io/python-pptx/_modules/pptx/chart/axis.html

Retrieves the category scale type for a date axis. This is always TIME_SCALE for a DateAxis.

```python
from pptx.enum.chart import XL_CATEGORY_TYPE

# Assuming 'axis' is an instance of DateAxis
category_type = axis.category_type
# category_type will be XL_CATEGORY_TYPE.TIME_SCALE
```

--------------------------------

### ImagePart.ext Property

Source: https://daobook.github.io/python-pptx/_modules/pptx/parts/image.html

Retrieves the file extension of the image part, such as 'png' or 'jpg'.

```python
image_part.ext
```

--------------------------------

### Get Category Type for Category Axis

Source: https://daobook.github.io/python-pptx/_modules/pptx/chart/axis.html

Retrieves the category scale type for a category axis. This is always CATEGORY_SCALE for a CategoryAxis.

```python
from pptx.enum.chart import XL_CATEGORY_TYPE

# Assuming 'axis' is an instance of CategoryAxis
category_type = axis.category_type
# category_type will be XL_CATEGORY_TYPE.CATEGORY_SCALE
```

--------------------------------

### Setting Pattern Fill

Source: https://daobook.github.io/python-pptx/_modules/pptx/dml/fill.html

Initializes a pattern fill object. Subsequent assignments to properties like `fore_color` will set the pattern and colors.

```python
pattFill = self._xPr.get_or_change_to_pattFill()
self._fill = _PattFill(pattFill)
```

--------------------------------

### Accessing Axis Title Object

Source: https://daobook.github.io/python-pptx/_modules/pptx/chart/axis.html

Get the AxisTitle object for an axis. This will add a title element to the XML if one does not exist.

```python
from pptx.chart.axis import _BaseAxis

# Assuming 'axis' is an instance of a class inheriting from _BaseAxis
axis_title = axis.axis_title
```

--------------------------------

### Execute OLE Action

Source: https://daobook.github.io/python-pptx/dev/analysis/shp-hyperlink.html

Configures a shape to perform an OLE action, such as 'Edit' (verb=0) or 'Open' (verb=1), using the 'ppaction://ole' action. This is applicable to embedded OLE objects.

```XML
<p:sp>
  <p:nvSpPr>
    <p:cNvPr id="9" name="Object 8">
      <a:hlinkClick r:id="" action="ppaction://ole?verb=0"/>
    </p:cNvPr>
  ...
</p:sp>
```

--------------------------------

### ImagePart._dpi Property

Source: https://daobook.github.io/python-pptx/_modules/pptx/parts/image.html

Internal property to get the horizontal and vertical DPI of the image. It relies on the Image object created from the blob.

```python
image_part._dpi
```

--------------------------------

### Getting OLE Object ProgID

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/graphfrm.html

Retrieve the 'progId' attribute of an embedded OLE object, which identifies the application used to open it.

```python
ole_format.prog_id
```

--------------------------------

### Getting Category Depth

Source: https://daobook.github.io/python-pptx/_modules/pptx/chart/category.html

Retrieves the hierarchical depth of the categories. Returns 1 for non-hierarchical categories, and 0 if no categories are present.

```python
depth = categories.depth
```

--------------------------------

### Add Paragraph Spacing Properties

Source: https://daobook.github.io/python-pptx/community/updates.html

Introduces Paragraph.space_before, Paragraph.space_after, and Paragraph.line_spacing for controlling paragraph spacing.

```python
Add Paragraph.space_before, Paragraph.space_after, and Paragraph.line_spacing
```

--------------------------------

### FreeformBuilder.move_to

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/freeform.html

Moves the drawing pen to a new location without drawing a line. Useful for starting new contours within the same freeform.

```APIDOC
## FreeformBuilder.move_to

### Description
Move pen to (x, y) (local coordinates) without drawing line. Returns this |FreeformBuilder| object so it can be used in chained calls.

### Method
`move_to(x, y)`

### Parameters
* **x** (int): The x-coordinate to move the pen to (local coordinates).
* **y** (int): The y-coordinate to move the pen to (local coordinates).

### Returns
This |FreeformBuilder| object, allowing for chained calls.
```

--------------------------------

### Add Hyperlink to a Text Run (Candidate Protocol)

Source: https://daobook.github.io/python-pptx/dev/analysis/txt-hyperlink.html

This is a candidate protocol for adding a hyperlink to a text run. It demonstrates setting the text and the hyperlink address.

```python
p = shape.text_frame.paragraphs[0]
r = p.add_run()
r.text = 'link to python-pptx @ GitHub'
hlink = r.hyperlink
hlink.address = 'https://github.com/scanny/python-pptx'
```

--------------------------------

### Get Shape Name

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/shapetree.html

Returns the appropriate shape name for the p:pic shape. The name is derived from the base filename of the video.

```python
@property
    def _shape_name(self):
        """Return the appropriate shape name for the p:pic shape.

        A movie shape is named with the base filename of the video.
        """
        return self._video.filename
```

--------------------------------

### Accessing Click Action Settings

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/base.html

Retrieve an ActionSetting object to manage click behaviors like hyperlinks or navigation to other slides. An ActionSetting object is always returned, even if no specific click behavior is defined.

```python
from pptx.shapes.base import BaseShape

# Assuming 'shape' is an instance of a class inheriting from BaseShape
# For example, a shape obtained from a slide:
# slide = prs.slides[0]
# shape = slide.shapes[0]

action_setting = shape.click_action
```

--------------------------------

### Crosses At Property

Source: https://daobook.github.io/python-pptx/_modules/pptx/chart/axis.html

Get or set the numeric value on the axis where the perpendicular axis crosses. Returns None if no crossing value is set.

```APIDOC
## crosses_at

### Description
Numeric value on this axis at which the perpendicular axis crosses. Returns |None| if no crossing value is set.

### Getter
```python
axis.crosses_at
```

### Setter
```python
axis.crosses_at = value
```

#### Parameters
* **value** (float or None) - The numeric value at which to set the crossing point, or None to remove the crossing value.
```

--------------------------------

### Apply Tint using TintAndShade Property

Source: https://daobook.github.io/python-pptx/dev/analysis/txt-font-color.html

This snippet demonstrates using the `TintAndShade` property to apply a tint. Note that a positive value between 0 and 1 is used, and it results in a `<a:tint>` element in the XML.

```python
fnt.Color.TintAndShade = 0.75

```

```xml
<a:rPr>
  <a:solidFill>
    <a:schemeClr val="accent1">
      <a:tint val="25000"/>
    </a:schemeClr>
  </a:solidFill>
</a:rPr>

```

--------------------------------

### Getting Minimum Scale Value

Source: https://daobook.github.io/python-pptx/_modules/pptx/chart/axis.html

Retrieve the minimum value of the axis scale. Returns None if the minimum scale is not explicitly set.

```python
from pptx.chart.axis import _BaseAxis

# Assuming 'axis' is an instance of a class inheriting from _BaseAxis
min_scale = axis.minimum_scale

if min_scale is None:
    print('Minimum scale is not explicitly set.')
else:
    print(f'Minimum scale is set to: {min_scale}')
```

--------------------------------

### ImagePart.scale() Method

Source: https://daobook.github.io/python-pptx/_modules/pptx/parts/image.html

Calculates scaled image dimensions in EMU. It preserves aspect ratio if only one dimension is provided, or returns native size if both are None.

```python
scaled_cx, scaled_cy = image_part.scale(scaled_cx, scaled_cy)
```

--------------------------------

### Jump to First Slide Action

Source: https://daobook.github.io/python-pptx/dev/analysis/shp-hyperlink.html

This XML snippet demonstrates how to configure a shape to jump to the first slide of the presentation using the 'ppaction://hlinkshowjump?jump=firstslide' action. The r:id attribute is empty as no external relationship is required.

```xml
<p:sp>
  <p:nvSpPr>
    <p:cNvPr id="7" name="Rounded Rectangle 6">
      <a:hlinkClick r:id="" action="ppaction://hlinkshowjump?jump=firstslide"/>
    </p:cNvPr>
    <p:cNvSpPr/>
    <p:nvPr/>
  </p:nvSpPr>
  <p:spPr>
    <a:xfrm>
      <a:off x="1020781" y="1684235"/>
      <a:ext cx="1495562" cy="1775031"/>
    </a:xfrm>
    <a:prstGeom prst="roundRect">
      <a:avLst/>
    </a:prstGeom>
  </p:spPr>
  <p:txBody>
    <a:p>
      <a:pPr algn="ctr"/>
      <a:r>
        <a:rPr lang="en-US" dirty="0" smtClean="0"/>
        <a:t>Click to go to Foobar Slide</a:t>
      </a:r>
      <a:endParaRPr lang="en-US" dirty="0" smtClean="0"/>
    </a:p>
  </p:txBody>
</p:sp>
```

--------------------------------

### ImagePart._px_size Property

Source: https://daobook.github.io/python-pptx/_modules/pptx/parts/image.html

Internal property to get the dimensions of the image in pixels (width, height). It uses the Image object created from the blob.

```python
image_part._px_size
```

--------------------------------

### RGBColor Initialization

Source: https://daobook.github.io/python-pptx/_modules/pptx/dml/color.html

Creates an immutable RGBColor object from three integer values (0-255). Raises ValueError for invalid input.

```python
class RGBColor(tuple):
    """
    Immutable value object defining a particular RGB color.
    """

    def __new__(cls, r, g, b):
        msg = "RGBColor() takes three integer values 0-255"
        for val in (r, g, b):
            if not isinstance(val, int) or val < 0 or val > 255:
                raise ValueError(msg)
        return super(RGBColor, cls).__new__(cls, (r, g, b))
```

--------------------------------

### ColorFormat

Source: https://daobook.github.io/python-pptx/_modules/pptx/dml/color.html

Provides access to color settings such as RGB color, theme color, and luminance adjustments.

```APIDOC
## Class: ColorFormat

### Description
Provides access to color settings such as RGB color, theme color, and luminance adjustments.

### Properties

- **brightness** (float): Read/write float value between -1.0 and 1.0 indicating the brightness adjustment for this color. -0.25 is 25% darker and 0.4 is 40% lighter. 0 means no brightness adjustment.
- **rgb** (RGBColor): |RGBColor| value of this color, or None if no RGB color is explicitly defined for this font. Setting this value to an |RGBColor| instance causes its type to change to MSO_COLOR_TYPE.RGB. If the color was a theme color with a brightness adjustment, the brightness adjustment is removed when changing it to an RGB color.
- **theme_color** (MSO_THEME_COLOR): Theme color value of this color. Value is a member of :ref:`MsoThemeColorIndex`, e.g. ``MSO_THEME_COLOR.ACCENT_1``. Raises AttributeError on access if the color is not type ``MSO_COLOR_TYPE.SCHEME``. Assigning a member of :ref:`MsoThemeColorIndex` causes the color's type to change to ``MSO_COLOR_TYPE.SCHEME``.
- **type** (MSO_COLOR_TYPE): Read-only. A value from :ref:`MsoColorType`, either RGB or SCHEME, corresponding to the way this color is defined, or None if no color is defined at the level of this font.

### Methods

- **from_colorchoice_parent(eg_colorChoice_parent)**: Class method to create a ColorFormat instance from a parent element.

### Exceptions

- **ValueError**: Raised when setting brightness to a value outside the range -1.0 to 1.0, or when trying to set brightness when the color type is None.
```

--------------------------------

### Add BMP Image Support

Source: https://daobook.github.io/python-pptx/community/updates.html

Adds support for including BMP image files.

```python
add BMP image support
```

--------------------------------

### Add Picture Placeholder and Image Properties

Source: https://daobook.github.io/python-pptx/community/updates.html

Adds PicturePlaceholder with insert_picture(), Picture.image property, and cropping methods. Also includes Shape.placeholder_format.

```python
add PicturePlaceholder with .insert_picture() method
add TablePlaceholder with .insert_table() method
add ChartPlaceholder with .insert_chart() method
add Picture.image property, returning Image object
add Picture.crop_left, .crop_top, .crop_right, and .crop_bottom
add Shape.placeholder_format and PlaceholderFormat object
```

--------------------------------

### Get Media rId

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/shapetree.html

Returns the rId of the RT.MEDIA relationship to the video part. This is the second of two relationships to the same part, historically used for media.

```python
@property
    def _media_rId(self):
        """Return the rId of RT.MEDIA relationship to video part.

        For historical reasons, there are two relationships to the same part;
        one is the video rId and the other is the media rId.
        """
        return self._video_part_rIds[0]
```

--------------------------------

### Get Video rId

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/shapetree.html

Returns the rId of the RT.VIDEO relationship to the video part. This is one of two relationships to the same part, historically used for video.

```python
@property
    def _video_rId(self):
        """Return the rId of RT.VIDEO relationship to video part.

        For historical reasons, there are two relationships to the same part;

```

--------------------------------

### Image.from_blob() Class Method

Source: https://daobook.github.io/python-pptx/_modules/pptx/parts/image.html

Creates a new immutable Image object from raw image binary data (blob). Optionally accepts a filename.

```python
Image.from_blob(blob, filename=None)
```

--------------------------------

### Get Poster Frame rId

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/shapetree.html

Returns the rId of the relationship to the poster frame image part. This image is used to represent the video before playback.

```python
@lazyproperty
    def _poster_frame_rId(self):
        """Return the rId of relationship to poster frame image.

        The poster frame is the image used to represent the video before it's
        played.
        """
        _, poster_frame_rId = self._slide_part.get_or_add_image_part(
            self._poster_frame_image_file
        )
        return poster_frame_rId
```

--------------------------------

### Run Custom SlideShow Action

Source: https://daobook.github.io/python-pptx/dev/analysis/shp-hyperlink.html

Sets a shape to trigger a custom slideshow using the 'ppaction://customshow' action. The 'return' query field can be used to control whether focus returns to the current show.

```XML
<p:sp>
  <p:nvSpPr>
    <p:cNvPr id="4" name="Rounded Rectangle 3">
      <a:hlinkClick r:id="" action="ppaction://customshow?id=0&amp;return=true"/>
      ...
</p:sp>
```

--------------------------------

### AutoShapeType Initialization and Caching

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/autoshape.html

This snippet demonstrates how the AutoShapeType class is initialized and how it uses a cache to ensure that only one instance exists for a given autoshape_type_id. It also shows the error handling for invalid IDs.

```python
class AutoShapeType(object):
    """
    Return an instance of |AutoShapeType| containing metadata for an auto
    shape of type identified by *autoshape_type_id*. Instances are cached, so
    no more than one instance for a particular auto shape type is in memory.

    Instances provide the following attributes:

    .. attribute:: autoshape_type_id

       Integer uniquely identifying this auto shape type. Corresponds to a
       value in ``pptx.constants.MSO`` like ``MSO_SHAPE.ROUNDED_RECTANGLE``.

    .. attribute:: basename

       Base part of shape name for auto shapes of this type, e.g. ``Rounded
       Rectangle`` becomes ``Rounded Rectangle 99`` when the distinguishing
       integer is added to the shape name.

    .. attribute:: prst

       String identifier for this auto shape type used in the ``<a:prstGeom>``
       element.

    .. attribute:: desc

       Informal string description of auto shape.

    """

    _instances = {}

    def __new__(cls, autoshape_type_id):
        """
        Only create new instance on first call for content_type. After that,
        use cached instance.
        """
        # if there's not a matching instance in the cache, create one
        if autoshape_type_id not in cls._instances:
            inst = super(AutoShapeType, cls).__new__(cls)
            cls._instances[autoshape_type_id] = inst
        # return the instance; note that __init__() gets called either way
        return cls._instances[autoshape_type_id]

    def __init__(self, autoshape_type_id):
        """Initialize attributes from constant values in pptx.spec"""
        # skip loading if this instance is from the cache
        if hasattr(self, "_loaded"):
            return
        # raise on bad autoshape_type_id
        if autoshape_type_id not in autoshape_types:
            raise KeyError(
                "no autoshape type with id '%s' in pptx.spec.autoshape_types"
                % autoshape_type_id
            )
        # otherwise initialize new instance
        autoshape_type = autoshape_types[autoshape_type_id]
        self._autoshape_type_id = autoshape_type_id
        self._basename = autoshape_type["basename"]
        self._loaded = True
```

--------------------------------

### Getting Maximum Scale Value

Source: https://daobook.github.io/python-pptx/_modules/pptx/chart/axis.html

Retrieve the maximum value of the axis scale. Returns None if the maximum scale is automatically determined by the data.

```python
from pptx.chart.axis import _BaseAxis

# Assuming 'axis' is an instance of a class inheriting from _BaseAxis
max_scale = axis.maximum_scale

if max_scale is None:
    print('Maximum scale is auto-determined.')
else:
    print(f'Maximum scale is set to: {max_scale}')
```

--------------------------------

### _BasePicture

Source: https://daobook.github.io/python-pptx/_modules/pptx/shapes/picture.html

Base class for shapes based on a `p:pic` element, providing common properties like cropping and line formatting.

```APIDOC
## _BasePicture

### Description
Base class for shapes based on a `p:pic` element.

### Properties
- **crop_bottom** (float) - Represents the relative portion cropped from the shape's bottom. Read/write. 1.0 represents 100%. Negative values and values greater than 1.0 are valid.
- **crop_left** (float) - Represents the relative portion cropped from the left of the shape. Read/write. 1.0 represents 100%. A negative value extends the side beyond the image boundary.
- **crop_right** (float) - Represents the relative portion cropped from the right of the shape. Read/write. 1.0 represents 100%.
- **crop_top** (float) - Represents the relative portion cropped from the shape's top. Read/write. 1.0 represents 100%.
- **line** (LineFormat) - An instance of |LineFormat|, providing access to the properties of the outline bordering this shape, such as its color and width.
- **ln** (Element) - The ``<a:ln>`` element containing the line format properties such as line color and width. |None| if no ``<a:ln>`` element is present.

### Methods
- **get_or_add_ln()** - Returns the `a:ln` element containing the line format properties XML for this `p:pic`-based shape.
```