C# - Intelligens címkék (SmartTag) készítése Office alkalmazásokhoz

forráskód letöltése
Ha bármely Office alkalmazásba (Word, Excel, stb.) a felhasználó szöveget gépel, akkor lehetőségünk van arra, hogy bizonyos általunk kiválasztott szavakhoz egyedi funkciót rendeljünk. Ez úgy néz ki, hogy ha az alkalmazásunk érzékeli a beírt szót, akkor ezt jelzi az adott Office alkalmazásnak, mely egy pontozott vonallal aláhúzza a szót. Ha ezek után a felhasználó az egérrel e szó fölé áll, akkor lehetősége van egy gyors menü megjelenítésére, melynek menüpontjait és a hozzá tartozó tetszőleges funkcióikat a mi alkalmazásunk szolgáltathatja.
E cikkben annak járunk utána, hogy miként készíthetünk SmartTag-et a Visual Studio.NET-tel.
A mellékelt példa használatához tegye a következőket:
Fordítsa le a melléklet példát.
Kattintson a mellékelt Registry.reg állományra és végezze el a tartalmának beírását a regisztrációs adatbázisba.
Indítson el egy Word-ot és gépelje be a „szoftver” szót.
A megvalósítandó feladat a következő legyen: készítsünk egy olyan SmartTag-et, mely figyeli, hogy a Word dokumentumaiba begépelésre kerül-e a „szoftver” szó. Ha igen, akkor ehhez két menüpontot hoz létre. Az első segítségével megváltoztathatjuk a beírt szó stílusát, míg a másodikat választva kicserélhetjük ezt a szót egy másik szövegre.
A megoldáshoz egy DLL-t kell készítenünk, így az új projekt létrehozásakor válasszuk a Class Library projekt típust. Mivel ezt COM DLL-ként szeretnénk üzemeltetni, így a megfelelő regisztrációhoz válasszuk ki a Solution Explorer-ben a SmartTagTest nevű projektünket, majd jobb gomb és Properties menüpont. A megjelenő ablakban válasszuk a Configuration Properties - Build elemet. Ekkor elérhetővé válik a Register for COM interop tulajdonság, melyet állítsunk igazra.
Ezek után válasszuk a Project - Add reference menüpontot. A megjelenő ablakban a COM lapon keressük elő a Microsoft SmartTags 1.0 Type Library elemet és adjuk hozzá projektünkhöz ezt a referenciát. A SmartTag csak az Office XP verziótól felfele érhető el, így ennél régebbi Office esetén ez a lehetőség nem áll rendelkezésünkre.
A Microsoft SmartTags 1.0 Type Library-ban van két olyan interfész, melyet implementálnunk kell az alkalmazásunkba, annak érdekében, hogy a kívánt funkciókat megvalósíthassuk.
Az egyik interfész az ISmartTagRecognizer, a másik az ISmartTagAction lesz.
ISmartTagRecognizer interfész felhasználása
Az ISmartTagRecognizer interfész abban játszik szerepet, hogy a begépelt szavakat azonosíthassuk és értesíthessük az adott Office alkalmazást az esetleges találatról.
A későbbi regisztrációhoz szükségünk lesz egy az osztályhoz rendelt GUID azonosítóra, így kérjünk egy újat a Tools - Create GUID menüpont kiválasztásakor, majd másoljuk be a kapott értéket a Guid attribútumba.
  [Guid("F84853C0-679A-4465-A167-737E93C812CF"), ComVisible(true)]
  public class Class1: ISmartTagRecognizer
  {
Alkalmazásunkban több SmartTag funkciót is megvalósíthatunk, de példa egyszerűségének kedvéért most csupán egyet készítünk, melynek kell adnunk egy belső nevet. Ez a név kerül a smartTagName belső változónkba.
    private string smartTagName="softwareonline#smarttag";
Az ISmartTagRecognizer interfész felhasználásakor több property-t és függvényt is fel kell használnunk, melyek segítségével a felismerési feladat elvégezhető.
Ilyen például a ProgId property, melyben egy a programunkat azonosító sztringet kell visszaadnunk. Ez a sztring kerül majd a DLL regisztrációjakor a Windows regisztrációs adatbázisába.
    public string ProgId
    {
      get
      {
        return "Animare.FirstSmartTagRecognizer";
      }
    } 
A SmartTagCount property-n keresztül adhatjuk meg, hogy alkalmazásunk hány SmartTag-et képvisel.
    public int SmartTagCount
    {
      get
      {
        return 1;
      }
    } 
A get_Name függvény egy olyan sztringet vár, mellyel az Office felhasználója is találkozik majd. Ezzel a névvel fog szembekerülni, amikor a SmartTag funkciót - melyet alkalmazásunk képvisel - engedélyez, letilt. A függvény paramétereként kapunk egy LocaleId nevű int típusú értéket. Ebből megtudhatjuk, hogy milyen nyelvterületen fut az alkalmazásunk, így ennek megfelelően több nyelvű programot is készíthetünk.
    public string get_Name(int LocaleId)
    {
      return "Software Online SmartTag teszt";
    }
A get_Desc függvényben egy tetszőleges szöveget adhatunk meg, melyben leírhatjuk, hogy mire is képes az alkalmazásunk. Itt szintén lehetőségünk van több nyelvű program készítésekor figyelembe venni, hogy melyik nyelvterületen kerül alkalmazásra programunk.
    public string get_Desc(int LocaleId)
    {
      return "SmartTag tesztalkalmazás";
    }
Megadhatunk egy url címet is a get_SmartTagDownloadURL függvény visszatérési értékében. Paraméterként kapunk egy SmartTagID azonosító számot, melyre csak akkor lenne szükségünk, ha a DLL-ünkben több, különálló SmartTag-et valósítanánk meg.
    public string get_SmartTagDownloadURL(int SmartTagID)
    {
      return "http://www.SoftwareOnline.hu";
    }
Minden SmartTag funkciót el kell látnunk egy belsőleg használt névvel. Ezt a get_SmartTagName függvénynél tehetjük meg. Itt szintén kapunk egy SmartTagID azonosító számot, melyre csak akkor lenne szükségünk, ha a DLL-ünkben több, különálló SmartTag-et valósítanánk meg.
    public string get_SmartTagName(int SmartTagID)
    {
      if (SmartTagID==1)
      {
        return smartTagName;
      }
      else
      {
        return "";
      }
    }
Az ISmartTagRecognizer leglényegesebb függvénye a Recognize. Ez kerül meghívásra akkor, ha változik a szöveg és ezen belül azonosítanunk kell a SmartTag által kezelendő szavakat. Az ellenőrizendő szöveget a Text paraméterben kapjuk. Ha ebben a szövegben megtaláljuk azt a szót, esetleg szavakat melyet keresünk, akkor ezt a szintén paraméterként kapott ISmartTagRecognizerSite interfész CommitSmartTag nevű függvényének meghívásával jeleznünk kell. Itt első paraméterként a SmartTag nevét kell megadni, melyet az adott szóhoz rendelünk. Második paraméterben azt tudatjuk, hogy a Text-en belül melyik az a pozíció, ahonnan a felismert szavunk kezdődik. (A karakterek számozása egytől indul!) A harmadik paraméterben kell megadnunk, hogy a felismert szavunk hány karakter hosszú. A második és harmadik paraméter alapján fogja az adott Office alkalmazás az általunk felismert szót pontozott vonallal aláhúzni.
    public void Recognize(string Text, SmartTagLib.IF_TYPE DataType, int LocaleID, SmartTagLib.ISmartTagRecognizerSite RecognizerSite)
    {
      int i=Text.ToLower().IndexOf("szoftver");
      if (i>=0)
      {
        RecognizerSite.CommitSmartTag(smartTagName, i+1, 8, RecognizerSite.GetNewPropertyBag());
      }
    }
A jelen példa egyszerűségének kedvéért nem vizsgáljuk azt az esetet, hogy a Text paraméterben többször előfordul a „szoftver” szó, így mindig csak az első találat fog megjelenni.
ISmartTagAction interfész felhasználása
Ha megtörtént egy-egy szó felismerése és az adott Office alkalmazás megjelölte a szót pontozott vonallal, akkor a felhasználó aktivizálhatja a SmartTag-et úgy, hogy az egérrel a szó fölé áll és a megjelenő kis ábrára kattint. Ekkor kap szerepet alkalmazásunkban az ISmartTagAction interfészt felhasználó osztály. Ilyenkor megjelenítésre kerül egy gyorsmenü. Ennek a menünek adhatunk egy tetszőleges fejléc szöveget, valamint menüpontokat, melyek közül a felhasználó szabadon választhat. A kiválasztott menüpont esetén ismét a mi DLL-ünk kapja meg a vezérlést és tetszőleges műveletet végezhet.
Az ISmartTagAction interfészt felhasználó osztályunknak ismét kell egy új GUID számot adnunk (Tool - Create GUID menüpont) ez a későbbi regisztrációkor válik szükségessé.
  [Guid("C7DFBDE3-9113-4f3f-89C5-C33BE30A5E9D"), ComVisible(true)]
  public class ActionClass: ISmartTagAction
  {
A megjelenő menü ablakának fejléc szövegét a get_SmartTagCaption függvény visszatérési értékeként adhatjuk meg.
    public string get_SmartTagCaption(int SmartTagID, int LocaleID)
    {
      return "Felismert szó";
    }
A get_VerbCount függvény visszatérési értékében határozhatjuk meg, hogy hány új menüpontot szeretnénk mi magunk megjeleníteni. Paraméterként megkapjuk, hogy melyik SmartTag-hez kell a menüpontokat rendelni, mivel a DLL-ünkben több SmartTag funkciót is megvalósíthatnánk.
    public int get_VerbCount(string SmartTagName)
    {
      if (SmartTagName=="softwareonline#smarttag")
      {
        return 2;
      }
      else
      {
        return 0;
      }
    }
Hogy mi legyen a menüpontok felirata, azt a get_VerbCaptionFromID függvényben adhatjuk meg. Ez annyiszor kerül meghívásra, amekkora értéket adtunk a get_VerbCount függvény visszatérési értékének. Hogy aktuálisan melyik menüpontról is van szó, azt a VerbID paraméterből tudhatjuk meg.
    public string get_VerbCaptionFromID(int VerbID, string ApplicationName, int LocaleID)
    {
      string s="";
      switch (VerbID)
      {
        case 1: 
          s="Első menüpont";
          break;
        case 2: 
          s="Második menüpont";
          break;
      }
      return s;
    }
Minden menüpontnak adhatunk egy belsőleg használt nevet is a get_VerbNameFromID függvényben. Itt szintén a paraméterként kapott VerbID értéke alapján dönthetjük el, hogy melyik menüpont nevét is kell visszaadnunk.
    public string get_VerbNameFromID(int VerbID)
    {
      string s="";
      switch (VerbID)
      {
        case 1: 
          s="First";
          break;
        case 2: 
          s="Second";
          break;
      }
      return s;
    }
Ha a felhasználó kiválaszt egy menüpontot a mi általunk szolgáltatottakból, akkor kerül meghívásra az InvokeVerb függvény. Itt szintén a VerbID paraméter árulkodik arról, hogy melyik menüpont lett kiválasztva. Az ApplicationName paraméterből megtudhatjuk, hogy melyik Office alkalmazásról is van szó. Ennek vizsgálatával például elérhetjük, hogy csak a Word-ben legyen használható az általunk megvalósított SmartTag. A Target property-ben az adott Office alkalmazástól függő objektumot kapunk. Ez minden esetben más és más. Jelen példánknál a Word esetében egy Word.Range osztály példánya lesz, melyen keresztül elérhetjük a SmartTag által kijelölt szót.
    public void InvokeVerb(int VerbID, string ApplicationName, object Target, SmartTagLib.ISmartTagProperties Properties, string Text, string Xml)
    {
      if (ApplicationName.IndexOf("Word.Application")>=0)
      {
        Word.Range wr = (Word.Range)Target;
        switch (VerbID)
        {
A példában az első menüpont kiválasztásakor a SmartTag által megjelölt „szoftver” szót megformázzuk vastag betűsre.
          case 1: 
            wr.Bold = Convert.ToInt32(true);
            break;
A második menüpontot választva a szót kicseréljük egy másik szövegre.
          case 2: 
            wr.Text = "http://www.SoftwareOnline.hu";
            break;
        }
      }
    }
Ezzel a SmartTag DLL-ünk készen is van. Használatához azonban nem elegendő a DLL regisztrálása a Windows regisztrációs adatbázisába, hanem még két további bejegyzés is szükséges a működéshez. Mindkettőre a HKEY_CURRENT_USER főkulcson belül van szükség. Az ISmartTagRecognizer interfészt felhasználó osztályunkhoz tartozó GUID számot kell a Software\Microsoft\Office\Common\Smart Tag\Recognizers\ kulcs alá bejegyezni. Az ISmartTagAction interfészt felhasználó osztályunkhoz tartozó GUID pedig a Software\Microsoft\Office\Common\Smart Tag\Actions\ kulcs alá kerül. Ezt a mellékelt Registry.reg állomány elvégzi helyettünk.
A telepített SmartTag-eket ellenőrizhetjük is, ha a Word-ben az Eszközök - Automatikus javítási beállítások menüpontját választjuk, majd a megjelenő ablakban az Intelligens címkék nevű lapra váltunk.