WKL Forms Object Library: kontrolniki za obrazce Access

Kontrolniki ActiveX za obrazce Microsoft Access, zgrajeni na .NET 10: drevesa, podatkovni listi, gantogram, postavitev, krmarjenje, gumbi, prikaz stanja, preverjanje vnosa in obvestila. Delujejo, kot da so del Accessa: zgodnja vezava z IntelliSense, nastavitve v listu z lastnostmi in v oknu oblikovalnika, dogodki v modulu obrazca, stalne številke napak ter delovanje v datotekah ACCDB in ACCDE in v okolju Access Runtime. Dokumentacija je namenjena razvijalcem v Accessu in VBA, ki kontrolnike postavljajo na obrazce, ter skrbnikom, ki jih nameščajo v računalnike uporabnikov. Trenutna izdaja: 2.0.0 – spremembe posameznih izdaj so opisane v datoteki CHANGELOG.md paketa izdaje. Do izdaje 1.68.2 se je knjižnica imenovala WKL Access Components.

Kontrolniki, ki jih Access ponuja v pogledu načrta (polje z besedilom, kombinirano polje in polje s seznamom, podobrazec, kontrolnik zavihka, gumb in podobni), zadoščajo za klasičen vnos podatkov. Manjka pa marsikaj, kar uporabniki danes pričakujejo od poslovne programske opreme: drevo, vezano na tabelo, podatkovni list, ki združuje, filtrira in sešteva kot sodobna mreža, gantogram, vrstica za krmarjenje, pripeta območja, ki sledijo velikosti okna, oznake stanja in kratka obvestila. Razvijalci v Accessu to vrzel zapolnjujejo z zasilnimi rešitvami – gnezdenimi podobrazci, neprekinjenimi obrazci s pogojnim oblikovanjem, nevezanim kontrolnikom Microsoft TreeView iz zbirke Common Controls, ki ga polni VBA. Takšne rešitve v vsaki aplikaciji zahtevajo lastno kodo, pa vendar se po videzu in vedenju še vedno razlikujejo od preostalega Officea.

Zbirke komponent, kot sta DevExpress WinForms in Telerik UI for WinForms, to težavo rešujejo za aplikacije .NET s kontrolniki Windows Forms. Obrazec Access pa sprejme samo kontrolnike ActiveX, zato teh zbirk v Accessu ni mogoče uporabiti. WKL Forms Object Library primerljive zmožnosti prinaša v Access v obliki kontrolnikov ActiveX, ki upoštevajo navade Accessa: RecordSource, LinkMasterFields, Requery, list z lastnostmi, dogodki v modulu obrazca, ACCDE in okolje Runtime.

Kje so meje: komponente ne nadomeščajo Accessovih kontrolnikov za preprosta vnosna polja, v poročilih ne delujejo kot seznami (seznam tam prikaže le obvestilo) in niso kontrolniki Windows Forms za aplikacije .NET.

• Namestitev izdanega paketa – predpogoji, bitna različica, registracija
• Prehod aplikacije na izdajo 2.0 – za aplikacije, zgrajene z izdajo 1.x
• Odpiranje oblikovalnika kontrolnika
• Gradnja skrbniške aplikacije – več kontrolnikov v eni aplikaciji: lupina s krmarjenjem in stranmi ter seznam s zasidranim obrazcem za urejanje, ki preverja vnos (vadnica predloge WKL Administration Shell Template)
• Vezava drevesa na tabelo in Mreža strank z naročili – vsakič en kontrolnik

• Vstavljanje kontrolnikov WKL v obrazce s kodo
• Ustvarjanje dogodkovnih procedur za kontrolnik
• Obravnava napak kontrolnikov WKL v VBA
• Izbira jezika komponent
• Lokalizacija aplikacije
• Usklajevanje barv s temo podatkovne zbirke
• Gradnja aplikacije Access iz besedilnih izvornih datotek

Opravila za posamezen kontrolnik najdete v njegovem pregledu (glejte Ključne zmožnosti).

Kontrolnike postavite na Accessove obrazce (ali na obrazce UserForm); komponente, označene z (objekt), ustvarite v VBA in nimajo lastnega okna.

Prikaz in urejanje zapisov iz tabel in poizvedb.

Posamezne vrednosti na obrazcu, vezane tako kot kontrolniki Accessa.

Razporejanje, deljenje ter razpiranje in strnjevanje območij obrazca.

Premikanje po aplikaciji in zaganjanje njenih ukazov.

Prikaz stanj, števil in rezultatov uporabniku.

Črtne kode, kode QR in slike na obrazcih in v poročilih.

Aplikacija kot celota in njeni viri podatkov.

FindNodes, filtri JPath in AsJSON uporabljajo mehanizem JSON iz knjižnice WKL Office JSON, ki je vključena v paket izdaje. Za hiter začetek je na voljo predloga lupine aplikacije z vrstico za krmarjenje, stranjo v podobrazcu in vrstico z ukazi (v paketu pod templates\app-shell).

Trije načini nastavljanja kontrolnika. List z lastnostmi (zavihek Drugo), okno oblikovalnika kontrolnika (Odpiranje oblikovalnika kontrolnika) in VBA prek lastnosti Object kontrolnika (Me!Tree1.Object.RecordSource = …). Vsi trije nastavljajo iste lastnosti, ki jih Access shrani z obrazcem.

Dogodki v modulu obrazca. Kontrolnik svoje dogodke sproži v modulu obrazca, na katerem je. Na zavihku Dogodek lista z lastnostmi jih Access ne navaja; procedure ustvarite na strani oblikovalnika Dogodki ali s seznamoma v oknu s kodo (Ustvarjanje dogodkovnih procedur za kontrolnik).

Vezava na podatke kot pri kontrolnikih Accessa. Seznami berejo RecordSource (tabelo, poizvedbo ali stavek SQL) in uporabnikove spremembe takoj zapišejo nazaj (AutoSave); za drevo zadoščajo RecordSource, KeyField, ParentField in TextField. Kaj mora vir zapisov omogočati, opisuje razdelek Urejanje in shranjevanje: predpogoji. V pogledu načrta kontrolnik vira podatkov ne bere, razen če je LivePreview nastavljen na True (Prikaz resničnih podatkov v pogledu načrta).

Stalne številke napak. Kontrolniki sprožajo napake s stalnimi številkami (konstante WklErrorCode) in z Err.Source = "WklForms"; besedila, ki jih vidijo uporabniki, so v jeziku komponent (Obravnava napak kontrolnikov WKL v VBA).

Jezik. Oblikovalniki, sporočila, Err.Description, priročni meniji in imena za bralnike zaslona so v angleščini, nemščini, slovenščini, hrvaščini ali italijanščini: v jeziku modela aplikacije, sicer v jeziku Officea, sicer sistema Windows, sicer v angleščini. Številke napak, imena lastnosti, shranjene vrednosti in IntelliSense so v vseh jezikih enaki; datumi in števila sledijo področnim nastavitvam sistema Windows (Izbira jezika komponent).

Barve. Vsak kontrolnik ima barvno shemo (ColorScheme). Privzeta samodejna shema najprej upošteva visoki kontrast sistema Windows, nato barve teme podatkovne zbirke Access (na primer „Riviera“), sicer uporabi svetlo paleto; svetlo, temno ali visokokontrastno shemo lahko izberete tudi izrecno. Kontrolniki ne sledijo temi Officea (barvita, temno siva, črna), ki jo Office hrani za vsak uporabniški račun posebej (Usklajevanje barv s temo podatkovne zbirke).

Ena knjižnica tipov, katere različica sledi vmesniku. Podatkovna zbirka se sklicuje na knjižnico tipov WKL Forms Object Library in ob odpiranju uporabi različico, registrirano v računalniku; glejte Različice.

• Namestitev izdanega paketa
• Prehod aplikacije na izdajo 2.0
• Uvajanje aplikacije s kontrolniki WKL v računalnike uporabnikov
• Izdaja aplikacije za produkcijo
• Kaj zapiše registracija za posameznega uporabnika
• Zbiranje sledi kontrolnikov WKL za podporo
• Licenciranje

Vsaka stran opiše simptom, različice, na katere se nanaša, vzrok in rešitev.

• Referenčni priročnik API za vse razrede in naštevanja (v angleščini): povezave so v stolpcu Dokumentacija v razdelku Ključne zmožnosti; zbirke in njihovi elementi: WklColumns · WklColumn · WklBands · WklBand · WklFormatRules · WklFormatRule · WklLinkDifferences · WklLinkDifference
• Oblike datotek: access-app.json · app-model.json · app-manifest.json · navpane.json

• CHANGELOG.md v paketu izdaje – kaj je spremenila posamezna izdaja
• Predloga lupine aplikacije (v paketu pod templates\app-shell, opisana v tamkajšnji datoteki README) – okvir aplikacije, ki ga zgradi orodje za gradnjo

Kontrolniki si delijo eno knjižnico tipov, WKL Forms Object Library, katere različica se zviša ob vsaki spremembi vmesnika. Izdaja ima različico x.y.z: x.y je različica knjižnice tipov, z šteje popravke brez spremembe vmesnika. Spremembe posameznih izdaj so opisane v datoteki CHANGELOG.md paketa izdaje; trenutna izdaja je 2.0.0.

Katera različica je registrirana. Za vsako bitno različico je hkrati registrirana le ena različica: ko registrirate izdajo, se za tega uporabnika odstrani registracija vseh drugih različic knjižnice, zato podatkovna zbirka nikoli ne uporabi starejše kopije. Registrirano različico ugotovite takole:

• V urejevalniku VBA Orodja › Sklici prikaže WKL Forms x.y Object Library za podatkovno zbirko, ki uporablja kontrolnike.

• V VBA:

  Dim r As Reference
  For Each r In References
      If r.Guid = "{A37D549E-FCD0-48EC-8B14-C7323B747E4F}" Then Debug.Print r.Major & "." & r.Minor, r.FullPath
  Next

• Komponente same navedejo svojo izdajo: WklApplication.Version jo vrne (1.55.0), WklApplication.Build pa izdajo, znak plus in celoten identifikator commita (potrditve sprememb) izvorne kode (1.55.0+ce4b826c...). V poročilu o napaki navedite Build.
• V lastnostih datoteke (Podrobnosti) Wkl.Forms.ObjectLibrary.dll kaže izdajo kot različico datoteke in izdelka, Wkl.Forms.ObjectLibrary.Managed.dll pa izdajo z identifikatorjem commita kot različico izdelka. Gradnja iz izvorne kode, ki ni bila potrjena v commitu, nima oznake; paket izdaje je vedno zgrajen iz commita, ki ga navaja njegova oznaka (tag).

Zagotovilo združljivosti. Ko je izdaja objavljena, se člani z DISPID-ji in razredi z GUID-i nikoli več ne spremenijo in ne odstranijo; nove izdaje samo dodajajo, vsak dodatek pa zviša različico knjižnice tipov. Obrazci hranijo nastavitve svojih kontrolnikov WKL v obrazcu (OleData), novejša izdaja pa prebere nastavitve, ki jih je shranila starejša; nastavitve, ki jih doda novejša izdaja, imajo v obrazcih iz starejše izdaje privzeto vrednost. Izdaja s popravki (z) ne spremeni nobenega člana.

Podatkovna zbirka s sklicem na starejšo različico deluje tudi z novejšo registracijo iste glavne različice: Access ob odpiranju podatkovne zbirke sklic razreši na registrirano knjižnico. Z izdajo 2.0 se začne nova glavna različica z imenom knjižnice WklForms; podatkovno zbirko, zgrajeno z izdajo 1.x, je treba enkrat prenesti (Prehod aplikacije na izdajo 2.0). Preden podatkovna zbirka uporabi člane novejše izdaje, jo znova prevedite (Razhrošči › Prevedi) in izdelajte novo datoteko ACCDE. V nasprotni smeri to ne deluje: podatkovna zbirka, zgrajena z novejšo izdajo, se s starejšo registracijo ne izvaja – sklic je prekinjen (MISSING), Access pa javi napako 459 ali „Object library not registered“. Najprej namestite komponente, šele nato podatkovno zbirko (Uvajanje aplikacije s kontrolniki WKL v računalnike uporabnikov). Pri obrazcih UserForm v Excelu in Wordu je drugače: Office od prve uporabe dalje hrani kopijo knjižnice za vsako različico, zato vsaka sprememba vmesnika zviša različico.

Glavna različica 2.0. Razrešitev sklica na novejšo registracijo je zagotovljena le znotraj njegove glavne različice. Access sicer prek istega ID-ja knjižnice poveže sklic podatkovne zbirke za izdajo 1.x tudi z izdajo 2.0, vendar ProgID-ji WklComponents.* takrat niso več registrirani. Izdaja 2.0 je preimenovala knjižnico iz WklComponents v WklForms, ProgID-je iz WklComponents.* v WklForms.* in zagonski modul v Wkl.Forms.ObjectLibrary.dll. Člani, DISPID-ji in GUID-i so enaki kot v izdaji 1.68, obrazci pa obdržijo svoje kontrolnike. Aplikacijo za izdajo 1.x enkrat prenesete (Prehod aplikacije na izdajo 2.0).

Podpora po kontrolnikih, vse v programu Access iz Microsoft 365:

„Osnovna uporaba“ pri obrazcih UserForm v Excelu in Wordu pomeni: kontrolnik je mogoče vstaviti na obrazec UserForm, ga vezati na njegove podatke, uporabljati iz VBA in shraniti z obrazcem UserForm; druga uporaba na obrazcih UserForm ni podprta.

WklTreeView, WklTreeList, WklGantt in WklGrid uporabnikovo spremembo – preimenovanje, premik, celico, kljukico, nov, kopiran ali izbrisan zapis – takoj zapišejo v RecordSource (AutoSave = True, privzeto). Ali to lahko uspe, je odvisno od vira zapisov.

• Vir zapisov mora biti v Accessu posodobljiv – preizkusite, ali lahko v njegovem podatkovnem listu spremenite vrednost. Tabela, izbirna poizvedba nad eno tabelo in besedilo SQL kot RecordSource shranjevanje omogočajo; poizvedba UNION, poizvedba z GROUP BY, prepustna poizvedba in povezana tabela ODBC brez enoličnega indeksa pa zavrnejo zapis z napako wkeSourceError (&H80040302): „Spremembe (Preimenovanje) vozlišča 2 ni bilo mogoče shraniti v „qUnion“: …“, nato sledi sporočilo programa Access, da posodobitev ni mogoča, ker je podatkovna zbirka ali objekt samo za branje. Nič se ne shrani, vozlišče pa obdrži besedilo iz vira.
• Polja, v katera vir ne more pisati, ne odprejo urejevalnika (WklGrid, WklTreeList, WklGantt, WklPropertyGrid): pri AutoSave = True seznam vir enkrat preveri – DAO-jeva Updatable in DataUpdatable, polja s samoštevilom, pri povezani tabeli ODBC pa gonilnik (stolpci IDENTITY, izračunani stolpci in stolpci rowversion). Take celice se vedejo kot ReadOnly. Pri AutoSave = False se nič ne izklopi, ker spremembo zapiše aplikacija sama. Dodajanje, brisanje, preimenovanje v WklTreeView in vlečenje ostanejo vklopljeni: zavrnitev se pokaže šele ob shranjevanju spremembe. Pri uporabnikovi spremembi se transakcija razveljavi, drevo se znova naloži, sproži se DataError z zgornjim besedilom, nato pa se prikaže okno s sporočilom, razen če DataError nastavi Response na acDataErrContinue (0). Pri viru, ki ga ni mogoče posodabljati, urejanje izklopite: AllowEditing = False (LabelEdit = False v WklTreeView), AllowAdditions = False, AllowDeletions = False in brez vlečenja in spuščanja.
• KeyField mora enolično določati en zapis. Zapis se poišče po ključu: pri tabeli ali poizvedbi v SQL (SELECT * FROM [source] WHERE [key] = …), pri besedilu SQL s FindFirst v naboru dynaset. Ključ, ki se pojavi dvakrat, zavrne zapis z wkeDuplicateKey (&H80040303): „Ključ 2 se v viru podatkov pojavi več kot enkrat. KeyField mora vsak zapis enolično označiti.“; nič se ne shrani. Sestavljeni ključ je KeyField = "OrderID;LineNo"; njegova polja gredo v isti pogoj z AND.
• Povezane tabele ODBC (SQL Server, Wkl OData) potrebujejo v programu Access enoličen indeks, ki ga Access ob povezovanju tabele prevzame iz primarnega ključa. Povezana tabela SQL Server s primarnim ključem shranjuje; ista tabela brez kakršnega koli indeksa je samo za branje in zavrne zapis kot zgoraj. Kontrolnik odpre svoj nabor dynaset z dbSeeChanges, kar zahtevajo tabele SQL Server s stolpcem IDENTITY. Prek gonilnika Wkl OData potrebuje tabela za pisanje tudi različico vrstice, ne glede na vrsto ključa. Brez nje Access poišče zapis tako, da primerja vse stare vrednosti (UPDATE … WHERE Id = ? AND Name = ?). Storitev takšne primerjave za tabelo s ključem ne ponuja, gonilnik pa je tudi ne opusti. Zapis se zavrne z wkeSourceError: „[Wkl][OData]Die Bedingung auf 'Name' laesst sich nicht uebersetzen; … ein Vergleich mit dem alten Wert wird von diesem Dienst nicht angeboten.“ Rešitev: tabeli dodajte stolpec rowversion ali pa za tabelo vklopite žig vrstice v storitvi (glejte dokumentacijo storitve). Nato tabelo znova povežite.
• Ena transakcija, eno mesto. Vsa pisanja enega uporabnikovega dejanja potekajo v transakciji privzetega delovnega prostora DAO, vključno z urejevalnikom celic v WklTreeList (BeforeUpdate z Action = wuaCellValue). Cancel v BeforeUpdate ali zavrnitev programa Access razveljavi celotno dejanje in znova naloži drevo. Pisanja, ki jih vaša koda izvede prek CurrentDb znotraj BeforeUpdate, spadajo v isti delovni prostor in se razveljavijo skupaj z njim. Cancel v ValidateCell pride pred vsakim pisanjem: urejevalnik se zapre, celica pa obdrži staro vrednost.
• En vir zapisov za vsa vozlišča. Drevesa, katerega vrste vozlišč prihajajo iz več tabel prek poizvedbe UNION, ni mogoče urejati neposredno v drevesu; preslikave vrste vozlišča v tabelo ni. Takšno drevo urejajte prek obrazcev: EditForms za izbrano vozlišče odpre Accessov obrazec njegove vrste (sourceKeys navaja ključ zapisa za njim, deleteFrom tabelo, iz katere se briše; glejte Urejanje zapisov v Accessovem obrazcu). Lahko pa nastavite AutoSave = False in spremembo shranite sami: drevo tedaj spremeni le prikaz, ne sproži BeforeUpdate, vaša obravnava ValidateCell, AfterLabelEdit, NodeDrop ali BeforeDelete pa zapiše zapis po ključu; če vaše pisanje ne uspe, tam nastavite Cancel.

Zaupanje. Kontrolniki se registrirajo kot varni za skriptno izvajanje in inicializacijo, čeprav člani zapisujejo datoteke (SaveToFile, Export…, SaveImage), odpirajo datoteke (AutoStart) in berejo datoteke, navedene v shranjenih lastnostih (WklImage, tudi iz omrežne skupne rabe). Uporabljajte jih samo v podatkovnih zbirkah iz zaupanja vrednih mest.

Kam na obrazec lahko postavite kontrolnik (stran posamezne komponente navaja njeno rešitev):

• Poročila: na poročilu seznami (WklTreeView, WklTreeList, WklGantt, WklGrid, WklPropertyGrid) namesto podatkov prikažejo obvestilo; WklBarcode in WklImage sta narejena za poročila (vezan kontrolnik izriše vrednost vsakega zapisa v predogledu tiskanja in v PDF); drugi kontrolniki na poročilih niso podprti. Hierarhična poročila zgradite z ravnmi združevanja in podporočili; pogled seznama prenesete ven z njegovim izvozom.
• Podprto: 32- in 64-bitni Access. Moduli VBA, ki jih zapišejo komponente (basWklRibbon, modul orodja za gradnjo, dodatek), ne deklarirajo funkcij API, zato ni treba prilagajati nobenega PtrSafe.
• Nastavitve za visok DPI niso podprte.
• Vlečenje in spuščanje deluje samo znotraj istega kontrolnika: vozlišča v WklTreeView, WklTreeList in WklGantt se premikajo ali kopirajo znotraj lastnega drevesa; vrstic v WklGrid ni mogoče vleči (sprejema samo datoteke iz Raziskovalca). Vlečenje zapisov iz enega kontrolnika na drugega – na primer številnih izbranih oseb na pravilo v drugem seznamu – ni mogoče. Rešitev: uporabnik izbira z MultiSelect, vi preberete SelectedKeys in dodelitev izvedete z ukazom (WklButton, ukaz priročnega menija ali RowCommand); ključ cilja vzamete iz SelectedKey drugega kontrolnika. Pri kopiranju vozlišč se polja s prilogami in polja z več vrednostmi ne kopirajo.
• AutoSave piše samo v RecordSource, ki ga Access lahko posodablja, s KeyField, ki enolično določa en zapis; poizvedba UNION, poizvedba z GROUP BY ali prepustna poizvedba ter povezana tabela brez enoličnega indeksa zavrnejo zapis ob shranjevanju spremembe, ne prej. Preslikave vrste vozlišča v tabelo ni. Drevo, naloženo iz Recordset ali iz datoteke, nima vira, v katerega bi lahko pisalo nazaj. Glejte Urejanje in shranjevanje: predpogoji.
• Filter vezanega kontrolnika je pogoj WHERE vira podatkov in po viru poizveduje vsakič znova; pri prepustni poizvedbi se na strežniku izvede celotna poizvedba.
• Access okna kontrolnika ActiveX v UI Automation ne navaja kot podrejenega elementa njegovega obrazca. Bralniki zaslona dosežejo mrežo prek fokusa; iskanje po drevesu elementov programa Access je ne najde.
• NodeFormat in CellFormat se sprožita samo pri FormatEvents = True. Vsak klic dogodka v Access traja nekaj milisekund, ki se seštejejo za vsako vidno vozlišče ali celico ob vsakem ponovnem izrisu.
• Izvoz: XLSX, XML in JSON; WklGantt zapisuje tudi slike, PDF in Microsoft Project XML. Druge oblike (XLS, CSV …) niso del kontrolnikov: datoteko XLSX odprite v Excelu in jo shranite v želeni obliki, ročno ali z nekaj vrsticami VBA. Izvoz v Excel v prikazani obliki izpusti podatkovne vrstice in nabore ikon, pri WklGantt pa puščice odvisnosti, osnovne načrte in roke (nimajo oblike celice).
• WklGantt: besedilo v PDF je del slike in ga ni mogoče iskati. Microsoft Project XML sledi shemi Project 2007: ročno razporejanje, vrzeli razdeljenih opravil in videz grafikona se ne izmenjujejo. Datoteke Project sledijo Microsoftovi objavljeni shemi in obliki datotek Project 2010; odpiranje v samem programu Microsoft Project ni podprto.

Kontrolniki in objekti ne vsebujejo preverjanja licence: ni licenčnega ključa, ni preverjanja v pogledu načrta in ne med izvajanjem, tudi ne v okolju Access Runtime ali na obrazcih UserForm v Excelu in Wordu. Podatkovna zbirka, ki jih uporablja, deluje v vsakem računalniku, v katerem je izdaja nameščena in registrirana (Uvajanje aplikacije s kontrolniki WKL v računalnike uporabnikov). Pogoji uporabe so tisti iz vaše pogodbe z dobaviteljem.