Using the Plot API

Applications may choose to use the plot API configuration-time capability, the plot-time capability, or both. They can also include provisions for multi-page documents, plotting to a file, error handling, and overriding the default plot progress dialog box.

Note:

Any time the plot engine is accessed through the plot API, the system will plot in the foreground if the BACKGROUNDPLOT system variable is set to 0, and in the background if the BACKGROUNDPLOT system variable is set to 1,2, or 3.

To use the basic configuration-time and plot-time APIs

1. Get the ID of the layout and make it active in the editor. (The layout must be active by the time beginPage() is called in step 7.)
2. Create an AcPlPlotInfo object and set the layout ID on it.
3. Implement a UI to create an AcDbPlotSettings object (optional).
4. Pass the AcPlPlotInfo object a pointer to the plot settings object (if there is one) using AcPlPlotInfo::setOverrideSettings().
5. Call AcPlPlotInfoValidator::validate() on the plot info object.

   This verifies that the overrides are compatible with the layout settings. For example, paper space and model space settings are mutually exclusive and the specified device must exist.

6. Create an AcPlPlotEngine object using AcPlPlotFactory::createPreviewEngine() or AcPlPlotFactory::createPublishEngine().
7. Call the following functions on the engine:
8. beginPlot()
9. beginDocument()
10. beginPage()
11. beginGenerateGraphics()
12. endGenerateGraphics()
13. endPage()
14. endDocument()
15. endPlot()

The following code illustrates a basic use of the API and the default plot progress dialog box, which is discussed further in Plot Progress Dialog Box.

AcPlPlotEngine* pEngine = NULL;
if(Acad::eOk==AcPlPlotFactory::createPublishEngine(pEngine))
{
    // Here is the progress dialog for the current plot process...
    AcPlPlotProgressDialog *pPlotProgDlg=acplCreatePlotProgressDialog(
        acedGetAcadFrame()->m_hWnd,false,1);
    pPlotProgDlg->setPlotMsgString(
        AcPlPlotProgressDialog::PlotMSGIndex::kDialogTitle,
        "Plot API Progress");
    pPlotProgDlg->setPlotMsgString(
        AcPlPlotProgressDialog::PlotMSGIndex::kCancelJobBtnMsg,
        "Cancel Job");
    pPlotProgDlg->setPlotMsgString(
        AcPlPlotProgressDialog::PlotMSGIndex::kCancelSheetBtnMsg,
        "Cancel Sheet");
    pPlotProgDlg->setPlotMsgString(
        AcPlPlotProgressDialog::PlotMSGIndex::kSheetSetProgressCaption,
        "Job Progress");
    pPlotProgDlg->setPlotMsgString(
        AcPlPlotProgressDialog::PlotMSGIndex::kSheetProgressCaption,
        "Sheet Progress");
    pPlotProgDlg->setPlotProgressRange(0,100);
    pPlotProgDlg->onBeginPlot();
    pPlotProgDlg->setIsVisible(true);
    es = pEngine->beginPlot(pPlotProgDlg);
    AcPlPlotPageInfo pageInfo;
    // Used to describe how the plot is to be made.
    AcPlPlotInfo plotInfo; 
    // First, set the layout to the specified layout 
    // (which is the current layout in this sample).
    plotInfo.setLayout(layoutId);// This is required.
    // Now, override the layout settings with the plot settings 
    // we have been populating.
    plotInfo.setOverrideSettings(pPlotSettings);
    // We need to validate these settings.
    AcPlPlotInfoValidator validator;
    validator.setMediaMatchingPolicy(
        AcPlPlotInfoValidator::MatchingPolicy::kMatchEnabled);
    es = validator.validate(plotInfo);
    // Begin document.  The version we call is dependent 
    // on the plot-to-file status.
    const char *szDocName=acDocManager->curDocument()->fileName();
    if(m_bPlotToFile)
        es = pEngine->beginDocument(plotInfo, szDocName, 
            NULL, 1, true, m_csFilename);
    else
        es = pEngine->beginDocument(plotInfo, szDocName);
    // Follow through sending commands to the engine, 
    // and notifications to the progress dialog.
    pPlotProgDlg->onBeginSheet();
    pPlotProgDlg->setSheetProgressRange(0, 100);
    pPlotProgDlg->setSheetProgressPos(0);
    es = pEngine->beginPage(pageInfo, plotInfo, true);
    es = pEngine->beginGenerateGraphics();
    es = pEngine->endGenerateGraphics();
    es = pEngine->endPage();
    pPlotProgDlg->setSheetProgressPos(100);
    pPlotProgDlg->onEndSheet();
    pPlotProgDlg->setPlotProgressPos(100);
    es = pEngine->endDocument();
    es = pEngine->endPlot();
    // Destroy the engine 
    pEngine->destroy();
    pEngine = NULL;
    // and the progress dialog.
    pPlotProgDlg->destroy();
else
    // Ensure the engine is not already busy...
    AfxMessageBox("Plot Engine is Busy...");
}