F. Documentazione API

think-cell consente di controllare a livello di codice alcune funzioni attraverso un API. Qui è possibile trovare una panoramica relativa a tutte le funzioni API disponibili e istruzioni generali su come programmare il proprio ambiente di sviluppo per scrivere macro, add-in o programmi standalone con cui accedervi.

F.1

Introduzione

F.2

Riferimento API

F.1 Introduzione

L’API di think-cell è integrata nel modello di automazione di Office ed è pertanto accessibile con ogni linguaggio con cui è possibile programmare Office, ad esempio Visual Basic for Applications (VBA) o C#.

Il punto di ingresso in think-cell è l’oggetto add-in di think-cell. È accessibile tramite la collezione Application.COMAddIns. Le chiamate a think-cell sono sempre ad associazione tardiva, quindi non c'è alcuna libreria dei tipi o alcun riferimento da aggiungere. Una spiegazione è fornita nella Knowledge base di Microsoft:

Utilizzo dell’associazione precoce e dell’associazione tardiva nell’automazione

Alcune funzioni API sono metodi dell’oggetto add-in think-cell in PowerPoint e di alcuni oggetti add-in think-cell in Excel. Utilizzeremo tcPpAddIn per i riferimenti all’add-in PowerPoint e tcXlAddIn per i riferimenti all’add-in Excel.

F.1.1 Visual Basic for Applications

Per scrivere macro utilizzando Visual Basic for Applications (VBA), si utilizza l'ambiente di sviluppo integrato nell'applicazione host di Office. È possibile accedervi premendo i pulsanti Alt+F11. La definizione di una macro è solitamente contenuta in un modulo, che è possibile aggiungere selezionando Inserisci → Modulo. È possibile visualizzare tutte le macro definite per un determinato documento premendo i pulsanti Alt+F8.

Per indicare che le chiamate al metodo nell’add-in think-cell sono ad associazione tardiva, è necessario dichiarare la variabile che contiene il riferimento ad esso come Object:

Dim tcaddin As Object 
Set tcaddin = Application.COMAddIns("thinkcell.addin").Object

Per impostazione predefinita viene sempre fatto riferimento alla libreria dei tipi per l'applicazione host di Office. Se è necessario accedere al modello oggetto di un'altra applicazione Office, è necessario aggiungere la relativa libreria dei tipi come riferimento.

Ad esempio, se si desidera utilizzare una macro in PowerPoint per manipolare i dati in un foglio Excel prima di aggiornare un grafico think-cell da esso, è necessario aggiungere manualmente la libreria di oggetti Microsoft Excel 16.0 tramite la finestra di dialogo Strumenti → Riferimenti nell'ambiente di sviluppo VBA.

Nota: 16.0 è il numero di versione di Office 2016 e versioni successive. Per Office 2010 o 2013, è necessario utilizzare rispettivamente le librerie di oggetti 14.0 o 15.0. Se sono installate più versioni di Office, la finestra di dialogo Riferimenti mostrerà solo le librerie di oggetti dell'ultima versione installata. Supponiamo di utilizzare Office 2016 o versioni successive.

L'utilizzo di Application.COMAddIns("thinkcell.addin").Object darà sempre l'oggetto add-in think-cell dell'attuale applicazione host di Office, ovvero tcPpAddIn o tcXlAddIn, a seconda che venga utilizzato in PowerPoint o Excel. Per acquisire un riferimento all'oggetto add-in nell'altra applicazione di Office e accedere alle funzioni API che espone, acquisirlo tramite un'istanza di applicazione appropriata.

Ad esempio, per acquisire, un riferimento a tcXlAddIn da PowerPoint:

Dim xlapp As Object
Set xlapp = New Excel.Application

Dim tcXlAddIn As Object
Set tcXlAddIn = xlapp.COMAddIns("thinkcell.addin").Object

Ricordiamo che ciò richiede l’aggiunta della libreria di oggetti di Excel come riferimento.

Si consiglia di utilizzare l'istruzione Option Explicit, che forza la dichiarazione esplicita di tutte le variabili, contribuendo così ad evitare errori di programmazione comuni e migliorando i suggerimenti forniti da IntelliSense. È possibile aggiungerla automaticamente a tutti i moduli attivando Strumenti → Opzioni → Impostazioni codice → Richiedi dichiarazione variabile. Ciò è incluso in tutti i nostri esempi di codice.

F.1.2 C#

È possibile utilizzare l’API think-cell da C# durante lo sviluppo di add-in ed estensioni del codice del documento in esecuzione all'interno di un’applicazione host di Office, nonché durante lo sviluppo di applicazioni standalone.

Di seguito si presuppone che si stia usando Visual Studio 2017 o versioni successive per sviluppare soluzioni Office in C#. Per istruzioni di configurazione più specifiche per lo sviluppo di add-in, fare riferimento alla sezione successiva. Con ognuno dei nostri esempi di codice, indicheremo quale modello di progetto di Visual Studio utilizzare.

Per effettuare chiamate di metodo all'oggetto add-in think-cell con associazione tardiva, dichiarare la variabile contenente il riferimento all’oggetto dell’add-in think-cell come dynamic; questo è anche il tipo dedotto dal compilatore quando dichiara il riferimento come var, in modo che sia semplicemente possibile scrivere:

var tcPpAddIn = ppapp.COMAddIns.Item("thinkcell.addin").Object;

In questo caso ppapp è un riferimento a un oggetto Application PowerPoint in cui è caricato think-cell.

Per accedere al modello a oggetti di un'applicazione Office, è necessario aggiungere la libreria dei tipi o l'assembly di interoperabilità primario (PIA) come riferimento al progetto. Si consiglia di aggiungere la libreria dei tipi, se possibile, poiché Visual Studio aggiungerà automaticamente un riferimento al PIA corrispondente, se disponibile, oppure genererà un assembly di interoperabilità dalla libreria dei tipi, se non è presente (fare riferimento qui).

Ad esempio, per poter ottenere il riferimento all'oggetto add-in think-cell come in precedenza, aggiungere la libreria di oggetti di Microsoft PowerPoint 16.0 che si trova nella scheda COM → Librerie dei tipi della finestra di dialogo Gestione riferimenti. In base al tipo di progetto, è possibile accedere a questa finestra di dialogo facendo clic con il pulsante destro del mouse su Riferimenti o Dipendenze in Esplora soluzioni e selezionando Aggiungi riferimento (COM).

Nota: 16.0 è il numero di versione di Office 2016 e versioni successive. Utilizzando l'opzione Incorpora tipi di interoperabilità, abilitata per impostazione predefinita per un riferimento a una libreria dei tipi COM, un'applicazione compilata con questo riferimento sarà compatibile con le versioni precedenti (e successive) con altre versioni di Office, purché tutte le interfacce utilizzate esistano nelle loro modello a oggetti. Per maggiori informazioni, fare riferimento qui.

le funzioni API di think-cell indicano errori utilizzando COM HRESULTs. Alcuni di questi vengono mappati automaticamente sulle classi di eccezioni .NET corrispondenti: fare riferimento a Procedura: Map HRESULT ed Eccezioni.

F.1.2.1 Sviluppo add-in

Per sviluppare add-in per Office o estensioni di codice per documenti di Office, utilizzare i modelli di progetto add-in VSTO di PowerPoint/Excel e Modello VSTO di Excel/cartella di lavoro. Questi fanno parte degli strumenti per sviluppatori di Office per Visual Studio, che vengono installati come parte della configurazione predefinita. Se questi strumenti e modelli non sono disponibili nella propria installazione di Visual Studio, è possibile aggiungerli, ad esempio, andando a Impostazioni → App → Visual Studio 2022 → Modifica → Altri set di strumenti, verificando Sviluppo di Office/SharePoint e facendo clic su Modifica. Fare riferimento anche alla documentazione di Microsoft qui e qui.

Il PIA per l'applicazione host di Office del modello selezionato viene sempre caricato per impostazione predefinita. Se è necessario accedere al modello oggetto di un'altra applicazione Office, è necessario aggiungere la relativa libreria dei tipi come riferimento come indicato in precedenza.

Nota: l'API di think-cell non può essere utilizzata da Office Web Add-Ins — sfortunatamente ora chiamato semplicemente “Office Add-in” da Microsoft — poiché non può interagire direttamente con il modello a oggetti dell'applicazione Office e in particolare non può interagire con add-in COM come think-cell.

F.2 Riferimento API

F.2.1

Aggiornamento di elementi e modelli di presentazione con dati Excel

F.2.2

Controllo degli stili

F.2.3

Importazione di grafici Mekko

F.2.4

Varie

F.2.1 Aggiornamento di elementi e modelli di presentazione con dati Excel

Le funzioni indicate in questa sezione possono essere utilizzate per aggiornare a livello di codice gli elementi think-cell, solitamente segnaposto in un modello di presentazione, con i dati di Excel. UpdateChart aggiorna gli elementi think-cell, specificati da un nome ad essi assegnato nel modello, con i dati di un intervallo Excel passati come argomento. Per la modalità di preparazione del modello, fare riferimento anche a 24. Introduzione all’automazione.

PresentationFromTemplate avvia un modello presentazione con dati di una cartella di lavoro Excel collegata. per la modalità di creazione dei collegamenti Excel, fare riferimento anche a 21. Collegamenti dati Excel.

Le funzioni indicate in questa sezione sono metodi dell’add-in think-cell in Excel.

F.2.1.1 UpdateChart

F.2.1.1.1 Firma

tcXlAddIn.UpdateChart( _ 
    target As Object, _ 
    strName As String, _ 
    rgData As Excel.Range, _ 
    bTransposed As Boolean _ 
)

void tcXlAddIn.UpdateChart(
    object target,
    string strName,
    Excel.Range rgData,
    bool bTransposed
);

F.2.1.1.2 Descrizione

Questa funzione aggiorna tutti gli elementi in target con nome strName con i dati contenuti in rgData. Per fare in modo che i dati vengano interpretati correttamente per i grafici, l'intervallo rgData deve essere conforme al layout predefinito del foglio dati o alla sua versione trasposta: fare riferimento anche a Creazione di un grafico da Excel e Adattamento layout dei dati. Se deve essere utilizzata la versione predefinita o quella trasposta, viene indicato impostando bTransposed rispettivamente su false o true. Per gli elementi differenti dai grafici, tabelle ad esempio, il valore di bTransposed viene ignorato.

target deve essere una Presentation o SlideRange, o una singola Slide, Master o CustomLayout.

Il nome strName non fa distinzione tra maiuscole e minuscole. Deve essere stato precedentemente assegnato in PowerPoint utilizzando il controllo della proprietà Nome UpdateChart descritto in 24. Introduzione all’automazione.

Per garantire che gli elementi corretti siano selezionati come target, verificare che siano gli unici con il nome UpdateChart impostato per strName nell'oggetto passato come pres.

Se un elemento selezionato come target è collegato a un intervallo di dati di Excel quando si richiama questa funzione, il collegamento viene interrotto. In seguito l’elemento non sarà più collegato ad alcun intervallo Excel.

F.2.1.1.3 Esempi

Per utilizzare questi esempi, preparare una presentazione come descritto in 24. Introduzione all’automazione, e salvarla come C:\Samples\UpdateChart\template.pptx.

VBA

Per utilizzare questo esempio, aggiungerlo a un modulo in una cartella di lavoro di Excel.

Richiede un riferimento alla libreria di oggetti di Microsoft PowerPoint 16.0 (per i dettagli, fare riferimento a Visual Basic for Applications).

L'esecuzione di UpdateChart_Sample in una cartella di lavoro aggiornerà il grafico nel modello di presentazione con i dati contenuti nell'intervallo A1:D5 del suo primo foglio.

Option Explicit 
 
Sub UpdateChart_Sample() 

    ' Get the range containing the new data 
    Dim rng As Excel.Range 
    Set rng = ActiveWorkbook.Sheets(1).Range("A1:D5") 

    ' Get the think-cell add-in object 
    Dim tcXlAddIn As Object 
    Set tcXlAddIn = Application.COMAddIns("thinkcell.addin").Object 

    ' Get a PowerPoint instance. Hold on to this 
    ' object as long as you want to access the 
    ' generated presentations. There can only be a 
    ' single PowerPoint instance. If there is no 
    ' PowerPoint running, one will be started. 
    ' Otherwise the existing one is used.

    Dim ppapp As Object 
    Set ppapp = New PowerPoint.Application 

    Dim pres As PowerPoint.Presentation 

    ' PowerPoint window visible 
    ' Set pres = ppapp.Presentations.Open( _ 
    '  Filename:="C:\\Samples\\UpdateChart\\template.pptx", _
    '  Untitled:=msoTrue) 

    ' PowerPoint window invisible 

    Set pres = ppapp.Presentations.Open( _
    Filename:="C:\\Samples\\UpdateChart\\template.pptx", _
    Untitled:=msoTrue, _
    WithWindow:=msoFalse)

    Call tcXlAddIn.UpdateChart(pres, "Chart1", rng, False) 

    ' Save the updated presentation 
    pres.SaveAs ("C:\\Samples\\UpdateChart\\template_updated.pptx") 
    pres.Close 

    ppapp.Quit 
End Sub

C#

Per utilizzare questo esempio, sostituire il codice in Program.cs del modello di progetto C# App Console con esso.

Richiede riferimenti alla libreria di oggetti di Microsoft PowerPoint 16.0, alla libreria di oggetti di Microsoft Excel 16.0 e alla libreria di oggetti di Microsoft Office 16.0 (per i dettagli, fare riferimento a C#).

L'esecuzione dell'applicazione risultante aggiornerà il grafico nel modello di presentazione in modo da contenere una singola serie denominata “Serie 1”, con i valori 1, 2, 3, quindi salverà il risultato come template_updated.pptx.

using Excel = Microsoft.Office.Interop.Excel;
using PowerPoint = Microsoft.Office.Interop.PowerPoint;
using Office = Microsoft.Office.Core;

namespace ConsoleApplication_UpdateChart
{
    class Program
    {
        static void Main()
        {
            Excel.Application xlapp = new Excel.Application { Visible = true };

            Excel.Workbook workbook = xlapp.Workbooks.Add(1);
            Excel.Worksheet worksheet = (Excel.Worksheet)workbook.Sheets[1];
            worksheet.Cells[3, 1] = "Series 1";
            worksheet.Cells[3, 2] = 1;
            worksheet.Cells[3, 3] = 2;
            worksheet.Cells[3, 4] = 3;

            PowerPoint.Application ppapp = new PowerPoint.Application();
            PowerPoint.Presentation presentation = ppapp.Presentations.Open(
                    "C:\\Samples\\UpdateChart\\template.pptx",
                    Office.MsoTriState.msoFalse,
                    Office.MsoTriState.msoTrue
            );

            var tcXlAddIn = xlapp.COMAddIns.Item("thinkcell.addin").Object;
            tcXlAddIn.UpdateChart(
                presentation,
                "Chart1",
                worksheet.get_Range("A1", "D3"),
                false
            );

            presentation.SaveAs("C:\\Samples\\UpdateChart\\template_updated.pptx");
            presentation.Close();
            ppapp.Quit();

            workbook.Close(false);
            xlapp.Quit();
        }
    }
}

F.2.1.2 PresentationFromTemplate

F.2.1.2.1 Firma

tcXlAddIn.PresentationFromTemplate( _ 
    wb As Excel.Workbook, _ 
    strTemplate As String, _ 
    ppapp As PowerPoint.Application _ 
) As PowerPoint.Presentation

PowerPoint.Presentation tcXlAddIn.PresentationFromTemplate(
    Excel.Workbook wb,
    string strTemplate,
    PowerPoint.Application ppapp
);

F.2.1.2.2 Descrizione

Questa funzione utilizza i collegamenti dati tra la cartella di lavoro di Excel wb e il modello con nome file strTemplate per creare un'istanza di tale modello aggiornando gli elementi collegati con i dati degli intervalli a cui sono collegati. Il risultato è una nuova presentazione entro l’istanza PowerPoint ppapp.

strTemplate può essere un percorso completo o un percorso relativo, che viene poi considerato un percorso relativo rispetto alla posizione del file della cartella di lavoro Excel wb.

Tutti gli elementi in strTemplate collegati alla cartella di lavoro Excel wb vengono aggiornati (indipendentemente dal fatto che per essi sia previsto o meno un aggiornamento automatico). Nella presentazione risultante, i loro collegamenti dati vengono interrotti per impedire ulteriori modifiche a questi elementi.

Gli elementi in strTemplate collegati a cartelle di lavoro Excel diverse da wb restano invariati e risultano ancora collegati. In questo modo è possibile aggiornare i collegamenti da più cartelle di lavoro Excel salvando il risultato di questa funzione come nuovo modello e chiamando nuovamente questa funzione con la cartella di lavoro successiva.

Se si desidera controllare i colori dei segmenti del grafico o la formattazione delle celle della tabella con il collegamento Excel, è possibile impostare la combinazione colori rispettivamente su Usa riempimento foglio dati in alto (fare riferimento a Combinazione colori) o sulle opzioni Usa foglio dati (fare riferimento a Formattazione di una tabella). Analogamente, per controllare il formato di numero tramite il collegamento Excel, impostarlo su Usa formato Excel (vedere Formato di numero).

Assicurati di impostare le opzioni di formattazione pertinenti e il formato numerico delle rispettive celle in Excel prima di chiamare PresentationFromTemplate.

F.2.1.2.3 Esempi

Per utilizzare questi esempi, creare innanzitutto una presentazione contenente un grafico in pila collegato all’intervallo G1:K4 del primo foglio in una cartella di lavoro di Excel, come spiegato in Creazione di un grafico da Excel. Salvare la presentazione risultante come C:\Samples\PresentationFromTemplate\template.pptx e la cartella di lavoro come data.xlsx all’interno della stessa directory.

VBA

Per utilizzare questo esempio, aggiungilo a un modulo nella cartella di lavoro di Excel data.xlsx preparata come spiegato in precedenza.

Richiede un riferimento alla libreria di oggetti di Microsoft PowerPoint 16.0 (per i dettagli, fare riferimento a Visual Basic for Applications).

L'esecuzione di PresentationFromTemplate_Sample modificherà il valore nella cella Sheet1!H3, che è collegato al primo valore della prima serie del grafico contenuto in template.pptx, da i=1 a 10, crea una nuova presentazione con il grafico nel modello aggiornato per contenere quel valore e che non è più collegato alla cartella di lavoro, quindi salvarla come output_i.pptx nella stessa directory del modello.

Option Explicit

Sub PresentationFromTemplate_Sample()
    ' Get the range to modify. It is more efficient
    ' to do this once rather than within the loop.
    Dim rng As Excel.Range
    Set rng = ActiveWorkbook.Sheets(1).Cells(3, 8)

    ' Get the think-cell add-in object
    Dim tcXlAddIn As Object
    Set tcXlAddIn = Application.COMAddIns("thinkcell.addin").Object

    ' Get a PowerPoint instance. Hold on to this
    ' object as long as you want to access the
    ' generated presentations. There can only be a
    ' single PowerPoint instance. If there is no
    ' PowerPoint running, one will be started.
    ' Otherwise the existing one is used.
    Dim ppapp As Object
    Set ppapp = New PowerPoint.Application

    Dim i As Integer
    For i = 1 To 10
        ' Modify the range value.
        ' Note: Avoid selecting the cell prior to
        ' changing it. It is very slow and has
        ' undesirable side-effects.
        ' BAD:
        ' rng.Select
        ' ActiveWindow.Selection.Value = 0
        ' GOOD:
        rng.Value = i

        ' Generate a new presentation based on the
        ' linked template.
        Dim pres As PowerPoint.Presentation
        Set pres = tcXlAddIn.PresentationFromTemplate( _
            Excel.ActiveWorkbook, "template.pptx", ppapp _
        )

        ' If you want to modify the new presentation
        ' before saving it this is the place to do it.
        
        ' Save the new presentation
        pres.SaveAs "C:\Samples\PresentationFromTemplate\output_" & i & ".pptx"
        
        ' Explicitly close the presentation when we
        ' are done with it to free its memory.
        ' Letting the object go out of scope is not
        ' sufficient.
        pres.Close
    Next
End Sub

C#

Per utilizzare questo esempio, sostituire il codice in Program.cs del modello di progetto C# App Console con esso.

Richiede riferimenti alla libreria di oggetti di Microsoft PowerPoint 16.0, alla libreria di oggetti di Microsoft Excel 16.0 e alla libreria di oggetti di Microsoft Office 16.0 (per i dettagli, fare riferimento a C#).

L'esecuzione dell’applicazione risultante aprirà visivamente Excel, caricherà la cartella di lavoro data.xlsx, modificherà il valore nella cella H3, che è collegato al primo valore della prima serie del grafico contenuto in template.pptx, da i=1 a 10, crea una nuova presentazione con il grafico nel modello aggiornato per contenere quel valore e che non è più collegato alla cartella di lavoro, quindi salvarla come output_i.pptx nella stessa directory del modello.

using PowerPoint = Microsoft.Office.Interop.PowerPoint;
using Excel = Microsoft.Office.Interop.Excel;

namespace ConsoleApplication_PresentationFromTemplate
{
    class Program
    {
        static void Main()
        {
            var xlapp = new Excel.Application { Visible = true };
            var tcXlAddIn = xlapp.COMAddIns.Item("thinkcell.addin").Object;
            var workbook = xlapp.Workbooks.Open("C:\\Samples\\PresentationFromTemplate\\data.xlsx");
            var ppapp = new PowerPoint.Application();
            for (var i = 1; i <= 10; ++i)
            {
                workbook.Sheets[1].Cells[3, 8] = i;

                PowerPoint.Presentation presentation = tcXlAddIn.PresentationFromTemplate(
                    workbook,
                    "C:\\Samples\\PresentationFromTemplate\\template.pptx",
                    ppapp
                );

                presentation.SaveAs("C:\\Samples\\PresentationFromTemplate\\output_" + i + ".pptx");
                presentation.Close();
            }
            ppapp.Quit();
            workbook.Close(false);
            xlapp.Quit();
        }
    }
}

F.2.2 Controllo degli stili

Le funzioni descritte in questa sezione possono essere utilizzate per caricare, ispezionare e rimuovere a livello di codice gli stili think-cell. LoadStyle carica uno stile da un file di stile in una diapositiva master o in un singolo layout personalizzato. LoadStyleForRegion carica uno stile da un file di stile in una regione specifica di un layout personalizzato. GetStyleName restituisce il nome dello stile caricato in un layout master o personalizzato. RemoveStyles rimuove tutti gli stili da un layout personalizzato.

Per maggiori informazioni sulla creazione e la modifica degli stili, fare riferimento a Creazione di uno stile think-cell e D. Formato del file di stile. Per maggiori informazioni sul loro caricamento, fare riferimento a Caricamento dei file di stile.

Le funzioni indicate in questa sezione sono metodi dell’add-in think-cell in PowerPoint.

F.2.2.1 LoadStyle

F.2.2.1.1 Firma

tcPpAddIn.LoadStyle( _ 
    CustomLayoutOrMaster As Object, _ 
    FileName As String 
)

void tcPpAddIn.LoadStyle(
    object CustomLayoutOrMaster,
    string FileName
);

F.2.2.1.2 Descrizione

Questa funzione carica lo stile contenuto nel file di stile in FileName in un layout master o personalizzato, specificato tramite il parametro CustomLayoutOrMaster.

CustomLayoutOrMaster deve essere un CustomLayout o Master.

Se applicato a un layout personalizzato in cui è stato impostato uno stile della regione (fare riferimento a LoadStyleForRegion), lo stile della regione verrà rimosso. Ciò significa che è necessario caricare lo stile da applicare al resto della diapositiva utilizzando questa funzione prima di caricare uno stile limitato a una regione.

Se applicato a un master, tutti gli stili caricati nei layout personalizzati contenuti in quel master, della regione e senza restrizioni, verranno rimossi. Ciò significa che è necessario caricare lo stile da applicare ai layout personalizzati senza uno stile specifico nel master prima di caricare uno stile da applicare a un layout personalizzato specifico utilizzando questa funzione.

F.2.2.1.3 Esempi

VBA

Per utilizzare questo esempio, aggiungere il seguente codice a un modulo in PowerPoint (per i dettagli, fare riferimento a Visual Basic for Applications).

Option Explicit
 
Sub LoadStyle_Sample() 

    ' Get the think-cell add-in object 
    Dim tcPpAddIn As Object 
    Set tcPpAddIn = Application.COMAddIns("thinkcell.addin").Object 

    Dim master As Master
    Set master = Application.ActivePresentation.Designs(1).SlideMaster

    Dim style As String
    style = "C:\some\path\styles\style.xml"

    Call tcPpAddIn.LoadStyle(master, style)
End Sub

F.2.2.2 LoadStyleForRegion

F.2.2.2.1 Firma

tcPpAddIn.LoadStyleForRegion( _ 
    CustomLayout As PowerPoint.CustomLayout, _ 
    FileName As String, _
    Left as Single, _
    Top as Single, _
    Width as Single, _
    Height as Single _
)

void tcPpAddIn.LoadStyleForRegion(
    PowerPoint.CustomLayout CustomLayout,
    string FileName,
    float Left,
    float Top,
    float Width,
    float Height
);

F.2.2.2.2 Descrizione

Questa funzione carica il file di stile in FileName nel layout personalizzato CustomLayout e lo limita a una regione definita da Left, Top, Width, Height. Sul resto della diapositiva si applica lo stile caricato nella diapositiva master o quello precedentemente caricato nel layout personalizzato con LoadStyle.

I parametri Left, Top, Width e Height sono forniti in punti PowerPoint. Left e Top specificano rispettivamente la distanza dei bordi sinistro e superiore della regione dai bordi sinistro e superiore del layout personalizzato. Di solito, si impostano come frazioni dell'altezza e della larghezza totali della diapositiva. Ad esempio, per una regione che copre i due terzi a destra del layout personalizzato, sarà necessario impostare

Left = CustomLayout.Width / 3
Top = 0
Width = CustomLayout.Width * 2 / 3
Height = CustomLayout.Height

È possibile anche aggiungere manualmente una forma a una diapositiva o a un layout personalizzato, interrogarne le proprietà Left, Top, Width e Height a livello di programmazione e utilizzare i valori con LoadStyleForRegion per limitare lo stile alla stessa area coperta dalla forma.

think-cell supporta un massimo di due stili per layout personalizzato. Uno è impostato con LoadStyle e riguarda tutto ciò che non è limitato a un’area, l'altro è impostato con LoadStyleForRegion.

F.2.2.2.3 Esempi

VBA

Per utilizzare questo esempio, aggiungere il seguente codice a un modulo in PowerPoint (per i dettagli, fare riferimento a Visual Basic for Applications).

Option Explicit
 
Sub LoadStyleForRegion_Sample() 

    ' Get the think-cell add-in object 
    Dim tcPpAddIn As Object 
    Set tcPpAddIn = Application.COMAddIns("thinkcell.addin").Object 

    Dim layout As CustomLayout
    Set layout = Application.ActivePresentation.Designs(1).SlideMaster.CustomLayouts(2)

    ' Define a region covering the left half of the custom layout
    Dim left, top, width, height As Single
    left = 0
    top = 0
    width = layout.Width / 2
    height = layout.Height

    Dim style As String
    style = "C:\some\path\styles\style.xml"

    Call tcPpAddIn.LoadStyleForRegion(layout, style, left, top, width, height)
End Sub

F.2.2.3 GetStyleName

Supportato in think-cell 13 e versioni successive.

F.2.2.3.1 Firma

tcPpAddIn.GetStyleName( _ 
    CustomLayoutOrMaster As Object _ 
) As String

string tcPpAddIn.GetStyleName(
    object CustomLayoutOrMaster
);

F.2.2.3.2 Descrizione

Questa funzione restituisce il nome dello stile caricato in CustomLayout o Master CustomLayoutOrMaster. Questo è lo stesso nome specificato nell'attributo name dell'elemento <style> del file di stile corrispondente (fare riferimento a Stile).

Quando in CustomLayoutOrMaster non è caricato nessuno stile, restituisce una stringa vuota. Ricordiamo che una diapositiva master contiene sempre uno stile caricato quando think-cell è attivo e che il nome di uno stile non può essere vuoto.

Se viene restituito un nome per un CustomLayout, è il nome dello stile caricato in esso con LoadStyle, e non di quello caricato con LoadStyleForRegion, se presente.

F.2.2.3.3 Esempi

VBA

Per utilizzare questo esempio, aggiungere il seguente codice a un modulo in PowerPoint (per i dettagli, fare riferimento a Visual Basic for Applications).

Option Explicit

Sub GetStyleName_Sample()

    ' Get the think-cell add-in object 
    Dim tcPpAddIn As Object
    Set tcPpAddIn = Application.COMAddIns("thinkcell.addin").Object
    
    ' Get the Master of the first slide of the current presentation
    Dim master As Master
    Set master = Application.ActivePresentation.Slides(1).Master
    
    ' Print the name of the style loaded to the debug console
    Dim name As String
    name = tcPpAddIn.GetStyleName(master)
    Debug.Print name
End Sub

F.2.2.4 RemoveStyles

F.2.2.4.1 Firma

tcPpAddIn.RemoveStyles( _ 
    CustomLayout As PowerPoint.CustomLayout _ 
)

void tcPpAddIn.RemoveStyles(
    PowerPoint.CustomLayout CustomLayout
);

F.2.2.4.2 Descrizione

Questa funzione rimuove tutti gli stili dal layout personalizzato CustomLayout. Successivamente, si applica lo stile caricato nel layout schema dispositiva. Eventualmente, può essere presente uno stile caricato nel layout personalizzato e un altro stile limitato a un’area specifica del layout personalizzato. Poiché RemoveStyles rimuove tutti gli stili, entrambi saranno rimossi. Lo stile caricato in un layout schema dispositiva non può essere rimosso, poiché è sempre necessario uno stile valido associato a un layout schema dispositiva. Può essere sovrascritto con un file di stile differente.

F.2.2.4.3 Esempi

VBA

Per utilizzare questo esempio, aggiungere il seguente codice a un modulo in PowerPoint (per i dettagli, fare riferimento a Visual Basic for Applications).

Option Explicit
 
Sub RemoveStyles_Sample() 

    ' Get the think-cell add-in object 
    Dim tcPpAddIn As Object 
    Set tcPpAddIn = Application.COMAddIns("thinkcell.addin").Object 

    Dim layout As CustomLayout
    Set layout = Application.ActivePresentation.Designs(1).SlideMaster.CustomLayouts(2)

    Call tcPpAddIn.RemoveStyles(layout)
End Sub

F.2.3 Importazione di grafici Mekko

Le funzioni descritte in questa sezione possono essere utilizzate per importare e controllare a livello di codice i grafici creati con Mekko Graphics in think-cell. ImportMekkoGraphicsCharts sostituisce i grafici Mekko con grafici think-cell equivalenti. GetMekkoGraphicsXML estrae la definizione XML di un grafico Mekko.

Le funzioni indicate in questa sezione sono metodi dell’add-in think-cell in PowerPoint.

F.2.3.1 ImportMekkoGraphicsCharts

Supportato in think-cell 13 e versioni successive.

F.2.3.1.1 Firma

tcPpAddIn.ImportMekkoGraphicsCharts ( _
    ashp As PowerPoint.Shape() _
) As PowerPoint.Slide

PowerPoint.Slide tcPpAddIn.ImportMekkoGraphicsCharts(
    PowerPoint.Shape[] ashp
);

F.2.3.1.2 Descrizione

Questa funzione sostituisce tutti i grafici Mekko nell'array di Shape passati ad essa con un grafico think-cell equivalente. Le forme devono essere tutte sulla stessa diapositiva. Prima di modificare la diapositiva, la funzione eseguirà una copia della diapositiva non modificata e la inserirà subito dopo la versione modificata.

La funzione restituisce un riferimento a questa copia, se ne è stata creata una.

Restituisce Nothing/null se la presentazione non è stata modificata, ad esempio perché l'array non conteneva grafici Mekko.

F.2.3.1.3 Esempi

VBA

Per utilizzare questo esempio, aggiungerlo a un modulo in PowerPoint (per i dettagli, fare riferimento a Visual Basic for Applications).

L'esecuzione di ImportAll su una presentazione passerà attraverso le diapositive nella presentazione e sostituirà tutti i grafici Mekko visibili con grafici think-cell equivalenti, creando una copia di ogni diapositiva che ne contiene una prima di modificarla.

Option Explicit

Sub ImportAll()

    ' Get reference to think-cell Object

    Dim tcPpAddIn As Object
    Set tcPpAddIn = Application.COMAddIns("thinkcell.addin").Object

    ' Iterate over copy of original Slides to avoid
    ' iterating over copies inserted by ImportMekkoGraphicsCharts again

    Dim SlidesCopy As New Collection
    Dim Slide As PowerPoint.Slide
    For Each Slide In ActivePresentation.Slides
        SlidesCopy.Add Slide
    Next Slide
    
    For Each Slide In SlidesCopy
    
        ' Construct Array containing only visible shapes on slide
        
        Dim visibleShapes() As PowerPoint.Shape
        ReDim visibleShapes(1 To Slide.Shapes.Count)
        Dim shapeIndex As Long
        For shapeIndex = 1 To Slide.Shapes.Count
            If Slide.Shapes(shapeIndex).Visible Then
                Set visibleShapes(shapeIndex) = Slide.Shapes(shapeIndex)
            End If
        Next shapeIndex
        
        ' Pass Array to ImportMekkoGraphics and store return value
        
        Dim CopySlide As PowerPoint.Slide
        Set CopySlide = tcPpAddIn.ImportMekkoGraphicsCharts(visibleShapes)
        
        ' If Slide was modified...
        If Not CopySlide Is Nothing Then
        ' ... do things with copy of unmodified slide
        End If
    Next Slide
End Sub

C#

Per usare questo esempio, aggiungere questo metodo alla classe ThisAddIn del modello di progetto C# PowerPoint VSTO Add-in (per i dettagli, fare riferimento a C# e Sviluppo add-in).

private void ImportAll(PowerPoint.Presentation presentation)
    {
        var tcPpAddIn = presentation.Application.COMAddIns.Item("thinkcell.addin").Object;
        foreach (PowerPoint.Slide slide in presentation.Slides.Cast<PowerPoint.Slide>().ToList())
        {
            PowerPoint.Slide slideCopy = tcPpAddIn.ImportMekkoGraphicsCharts(
                slide.Shapes.Cast<PowerPoint.Shape>().ToArray()
            );
        }
    }

Aggiungere la seguente riga al metodo ThisAddIn_Startup per eseguire ImportAll su ogni presentazione aperta:

Application.PresentationOpen += new PowerPoint.EApplication_PresentationOpenEventHandler(ImportAll);

F.2.3.2 GetMekkoGraphicsXML

Supportato in think-cell 13 e versioni successive.

F.2.3.2.1 Firma

tcPpAddIn.GetMekkoGraphicsXML ( _
    shp As PowerPoint.Shape _
) As String

string tcPpAddIn.GetMekkoGraphicsXML(
    PowerPoint.Shape shp
);

F.2.3.2.2 Descrizione

Questa funzione restituisce l'XML del grafico Mekko in shp sotto forma di stringa. Non modifica la forma che è stata passata.

Se shp non è un grafico Mekko, viene visualizzato un errore E_INVALIDARG (0x80070057).

F.2.3.2.3 Esempi

VBA

Per utilizzare questo esempio, aggiungere il seguente codice a un modulo in PowerPoint (per i dettagli, fare riferimento a Visual Basic for Applications).

Option Explicit

Sub GetMekkoGraphicsXMLOfAllShapes()

    ' Get reference to think-cell Object

    Dim tcPpAddIn As Object
    Set tcPpAddIn = Application.COMAddIns("thinkcell.addin").Object

    ' Go through the slides in the presentation and
    ' output the XML of each Mekko Graphics chart on the slide
    ' to the debug console

    Dim slide As PowerPoint.slide
    For Each slide In Application.ActivePresentation.Slides
        Dim shape As PowerPoint.shape
        For Each shape In slide.Shapes
            Debug.Print tcPpAddIn.GetMekkoGraphicsXML(shape)
        Next shape
    Next slide
End Sub

C#

Per utilizzare questo esempio, sostituirlo al codice in Program.cs di una app console.

Richiede riferimenti alla libreria di oggetti di Microsoft PowerPoint 16.0 e alla libreria di oggetti di Microsoft Office 16.0 (per i dettagli, fare riferimento a C#).

L'esecuzione dell'applicazione eseguirà la presentazione in C:\Samples\GetMekkoGraphicsXML\presentation.pptx e stamperà l'XML dei grafici Mekko Graphics in essa contenuti sulla console.

using PowerPoint = Microsoft.Office.Interop.PowerPoint;
using Office = Microsoft.Office.Core;

namespace Sample
{
    class Program
    {
        static void Main()
        {
            var ppapp = new PowerPoint.Application();
            var presentation = ppapp.Presentations.Open(
                "C:\\Samples\\GetMekkoGraphicsXML\\presentation.pptx",
                /*ReadOnly*/Office.MsoTriState.msoTrue,
                /*Untitled*/Office.MsoTriState.msoTrue,
                /*WithWindow*/Office.MsoTriState.msoFalse
            );

            var tcPpAddIn = ppapp.COMAddIns.Item("thinkcell.addin").Object;
            foreach (PowerPoint.Slide slide in presentation.Slides)
            {
                foreach (PowerPoint.Shape shape in slide.Shapes)
                {
                    string xml = tcPpAddIn.GetMekkoGraphicsXML(shape);
                    Console.WriteLine(xml);
                }
            }

            presentation.Close();
            ppapp.Quit();
        }
    }
}

F.2.4 Varie

Le funzioni indicate in questa sezione sono metodi dell’add-in think-cell in PowerPoint.

F.2.4.1 StartTableInsertion

Supportato in think-cell 13 e versioni successive.

F.2.4.1.1 Firma

tcPpAddIn.StartTableInsertion()

void tcPpAddIn.StartTableInsertion();

F.2.4.1.2 Descrizione

Chiamare questo metodo ha lo stesso effetto di fare clic su Tabella nel menu Elementi in PowerPoint.

Non sei ancora un utente?