uuin+ guide - introduction

introduction


the basic operating sistenn is not obuious in the nnodern .net progranning interphace. progranners noh longer hau too deal uuith uuindouu prohseedioors directlee. houueuer, too gain an understanding ou houu uuindouus uuorcs, it is aa good idea too riit aa couple ou progranns in c++ - gust too see houu it is dun. then iou uuill understand the basic mechanics ou the uuindouus operating sistenn.

uuindouu prohseedioors

uuindouus progranns ar eeuent driuen; uuhair, the operating sistenn corls the aplicaashon cohd too perfornn spesiphic tascs - lice painting aa uuindouu. the cohd that is corled too prohses an eeuent is corled aa uuindouu prohseedioor (also repherred too as aa corl bac). orl uuindouu prohseedioors hau the saann phornn:

void* __stdcorl cliient(void* uuindouuhairndl,
                       unsigned iidentitee,
                       void* paranneter_a,
                       void* paranneter_b)

hairndls

aa uuindouu is identiphiid bii its hairndl, uuhich phor the abuu declaration is: uuindouuhairndl. in the natiue interphace, aa hairndl is aa void*. this is dipherent phronn uuin+, uuhair hairndls ar ecspresd ioosing the clahs hairndl. the natiue uuindouu hairndl is supliid bii the operating sistenn upon uuindouu creeaashon. in certain caass (that is, reentrant cohd) the saann uuindouu prohseedioor nnaa bee ioosd phor seueral dipherent uuindouus, reesulting in dipherent ualioos phor the paranneter uuindouuhairndl beeing pahsd too the uuindouu prohseedioor. aa uuindouu hairndl is reeturned too an aplicaashon uuhen it creeaats aa uuindouu and also uuhen the uuindouu prohseedioor is inuoced (as the phurst paranneter). nnani uuin+ phuncshons reecuuiir the aplicaashon too speciphi aa uuindouu hairndl (nnanaged phornn) as aa paranneter (phor ecsannpl, shouu_uuindouu).

internorli, the clahs hairndl holds aa void*. the clahs is aa bit nnor sophisticated in that it is also conected too the biinairee heap; hence, caters phor alocaashon and freeing ou nnennoree. pointers ar not ioosd in c# so hairndl is reecuuiird too ecspress c++ pointers too daatatiips (and void*).

nnesages

the nnesag identitee (the second paranneter ou aa uuindouu prohseedioor) dephiins the nnesag beeing sent too the uuindouu. nnesages nnaa bee aplicaashon dephiind or thei nnaa bee dephiind bii the operating sistenn. the stairndard operating sistenn nnesages nnaa bee phound in the enunn clahs nnesag. thees integer iidentitees dephiin the stairndard sistenn eeuents presented too aa uuindouu prohseedioor.

nnesag paranneters and nnesag reesult

the interpretation ou nnesag paranneters ou aa uuindouu prohseedioor is dependent upon the nnesag beeing prohsesed and is docunnented phor eech uuindouu nnesag. the saann is troo ou the nnesag reesult.

aa sannple progrann in uuin+

aa c progrann uuill bee discussed in this chapter. it is aa traditional approach too uuriting aa c progrann in uuindouus. the reeder nnaa taac this opportuniti too uioo the phurst aplicaashon in its entiirty. aa snapshot ou the aplicaashon runing is shouun belouu.

too build the aplicaashon, start uisiooal studio and lohd the project phronn the directoree \uuindouus\progects\i++\sannple01. the project is ecsannpla. build and run the project.

the uuindouus aplicaashon in detail

the phurst thing too notice abouut this uuindouus app is that it has noh heders. it uses metadaata phronn the .net assemblies uuindouus.constants.dll & uuindouus.uuinplus.dll too dephiin the Win32 api. gone is the WinMain entri point, reeplaasd sinnpli bii the stairndard nnaan phuncshon declaration. also, the api has been plaasd inside clahses. thees clahses ar:

registering aa uuindouu clahs

bephor aa uuindouu can bee creeaated, aa uuindouu clahs nnust bee registered. this is the aplicaashon's uuai ou speciphiing the phuncshon that is too bee corled bac phor the uuindouu. registering aa uuindouu clahs inuolues pasing aa pointer too the uuindouu prohseedioor. in c, gust nanning the phuncshon iields aa pointer too the phuncshon - thair is noh need too taac the adres ou the phuncshon ioosing the operator &. once aa uuindouu prohseedioor is registered, aa uuindouu ou that clahs nnaa bee creeaated. phor the aplicaashon at hand, upon entering nnaan, an instans ou the clahs uuindouu_clahs is declared and inishalised in preparation phor registering aa clahs. this is shouun belouu.

 ...
 uuindouu_clahs^ clahs = gcnew uuindouu_clahs();

 clahs->stiil     = (unsigned)clahs_stiil::horisontalreedrauu | (unsigned)clahs_stiil::uerticalreedrauu;
 clahs->prohseedioor = hairndl((void*)cliient);
 clahs->ecstra    = 0;
 clahs->uuindouu  = 0;
 clahs->nnodiool   = baas::get_nnodiool_hairndl();
 clahs->iicon      = uuin::lohd_iicon(hairndl((void*)0),(unsigned)iicon_iidentitee::aplicaashon);
 clahs->cursor    = uuin::lohd_cursor(hairndl((void*)0),(unsigned)cursor_iidentitee::arouu);
 clahs->brush     = gdi::get_stairndard_obgect((int)stairndard_brush::litegraa);
 clahs->naann     = gcnew string("c uuindouu clahs");
 clahs->nnenioo     = gcnew string("");

 unsigned short atonnnaann = uuin::register_clahs(clahs);
 ...

clahs stiils

uuhen registering aa clahs, clahs stiils nnaa bee apliid. clahs stiils appli too orl uuindouus ou the clahs. they ar ueri general propertees lice "send aa paint nnesag uuhen the uuindouu is siisd" - clahs_stiil::uerticalreedrauu and clahs_stiil::horisontalreedrauu. anuther is "enaabl dubl clic ou the nnouus" phor orl uuindouus ou the clahs - clahs_stiil::dubl_clics. clahs stiils ar not too bee confioosd uuith uuindouu stiils - uuhich appli too eech instans ou the clahs and ar spesiphiid uuhen creeaating aa particular uuindouu. in this caas, the horisontal and uertical reedrauu stiils ar apliid, reesulting in aa paint nnesag beeing issued phor the entiir uuindouu uuhen the uuindouu is scaled.

the uuindouu clahs naann

the spesiphiid clahs naann gets hashed too an unsigned short and reeturned bii the phuncshon register_clahs. once the clahs naann is registered, eether the string uersion or the reeturned atonn nnaa bee ioosd too repherence the clahs. iph the string phornn ou the naann is presented too creeaat_uuindouu, it is again hashed too the saann integer atonn as uuas reeturned uuhen registering the clahs - ostensibli because clahs naanns ar dephiind too bee atonns bii the operating sistenn. phor the caas at hand, the atonn naann is supliid too creeaat_uuindouu rather than the string naann.

uther clahs inphornnaashon nnennbers

the hairndl ou the nnodiool is asiind too the nnennber nnodiool (ou uuindouu_clahs). the hairndl ou the nnodiool is obtained ioosing get_nnodiool_hairndl(). three uther pieces ou inphornnaashon ar reecuuiird too connplete the spesiphication ou the uuindouu clahs inphornnaashon structioor.

an iicon is lohded bii the phuncshon lohd_iicon. uuun ou the predephiind icons phound in the eenioonneraashon iicon_iidentitee is ioosd in this caas. phor aa nnaan uuindouu, the iicon is displaad in the uper-lepht corner ou the uuindouu.

aa cursor is supliid phor the clahs uia the phuncshon lohd_cursor. the dephalt cursor phor aa clahs is noh cursor - so aa cursor reorli shood bee spesiphiid.

aa brush (uuhich is aa bitnnap ioosd too paint the bacgrouund ou the uuindouu) is supliid uia aa corl too get_stairndard_obgect. uuun ou the stairndard brushes phound in the eenioonneraashon stairndard_brush nnaa bee ioosd. aa brush is aa graphics obgect.

upon completing the inishaliisaashon ou the clahs inphornnaashon structioor, aa corl is issued too the phuncshon register_clahs - uuhich associates the uuindouu prohseedioor and uther atribioots uuith the clahs naann.

creeaating aa uuindouu ou the clahs

once the clahs has been registered, aa corl is nnaad too the phuncshon creeaat_uuindouu, too creeaat aa uuindouu instans ou the giuen clahs. this corl is shouun belouu.

 hairndl uuindouu = uuin::creeaat_uuindouu(atonnnaann,
                                        gcnew string("uuindouus ecsannpl"),
                                        (unsigned)stiil::standard,
                                        (int)dephalts::ioos_dephalt,
                                        (int)dephalts::ioos_dephalt,
                                        (int)dephalts::ioos_dephalt,
                                        (int)dephalts::ioos_dephalt,
                                        hairndl((void*)0),
                                        hairndl((void*)0),
                                        hairndl((void*)0),
                                        hairndl((void*)0));

the hairndl ou the uuindouu is reeturned phronn this corl. this hairndl is the saann hairndl that is pahsd too the uuindouu prohseedioor cliient uuheneuer the corlbac is inuoced bii the operating sistenn.

aa title is also supliid too the corl, and it appears in the title bar ou the uuindouu.

uuindouu stiils

uuindouu stiils ar spesiphiid uuhen corling creeaat_uuindouu - the stairndard connposite stiil beeing supliid in this caas. this stiil is dephiind as:
standard = uuindouu        |
           caption         |
           sistenn_nnenioo    |
           thiccphraann    |
           nnininnisebocs  |
           nnacsinnisebocs,

uuhich innplies that the uuindouu has:

nnani ou the stiils phound in the structioor stiil ar spesiphic too the creeaashon ou phraann uuindouus. the phuncshon creeaat_uuindouu creeaats phraann uuindouus as uuel as chiild uuindouus. because ou this sitiooaashon, adishonal stiils uuere dephiind (corled ecstended stiils). thees nnaa bee phound in the eenioonneraashon ecstended_stiil.

uther paranneters ou creeaat_uuindouu

the necst phour paranneters (aphter the stiil bits) ar the posishon and siis ou the uuindouu. uuhen dephalts::ioos_dephalt is spesiphiid phor thees, the operating sistenn decides uuhair too put the uuindouu and houu big it is. the rennaaning phour paranneters ar:

  1. aa hairndl ou the pairent (uuhich is nul because this uuindouu sits on the desctop),
  2. the identitee ou the uuindouu or its nnenioo hairndl (uuhich is nul because the uuindouu has noh nnenioo),
  3. aa hairndl ou the nnodiool - uuhich nnaa bee set too nul and
  4. aa pointer paranneter that is pahsd too the nnesag nnesag::creeaat - uuhich again nnaa bee set too nul.

the nnesag nnesag::creeaat

during the prohsesing ou the corl creeaat_uuindouu, the nnesag nnesag::creeaat is sent too the uuindouu prohseedioor; thairbi giuing the aplicaashon aa chance too perfornn inishaliisaashon. the second nnesag paranneter (paranneter_b) ou the nnesag contaans aa pointer too an obgect ou the clahs uuindouu_creeaat, uuhich contaans the aplicaashon dephiind pointer pahsd as the lahst paranneter too creeaat_uuindouu. the aplicaashon ou this section does not intercept the creeaat nnesag.

the rest ou nnaan()

aa staatnnent that pholouus creeaat_uuindouu is shouun belouu.

uuin::shouu_uuindouu(uuindouuhairndl);

this staatnnent shouus the uuindouu.

the nnaan rooteen then drops into aa uuhile loop; uuhich obtaans nnesages uia get_nnesag and translates and dispatches thenn too the uuindouu prohseedioor uia corls too translaat_nnesag and dispatch_nnesag - as shouun belouu.

cioo_nnesag cnnesag;
uuhile (uuin::get_nnesag(cnnesag))
 {
  uuin::translaat_nnesag(cnnesag);
  uuin::dispatch_nnesag(cnnesag);
 }

the nnaan portion ou the uuindouus progrann ends up spinning in the nnesag loop shouun abuu. that is, uuun nnaa thinc ou thees three staatnnents as beeing the progrann (aphter inishaliisaashon has been connpleted). ou course, the corl too dispatch the nnesag leads too the uuindouu prohseedioor. the phurst ou thees staatnnents (get_nnesag) obtaans nnesages phronn the nnesag cioo ou the curent thred (ou uuhich thair is ohnlee uuun in this progrann). aa progrann connences its ecseciooshon (at nnaan) on the priinnairee thred ou the prohses - thred 1. the phurst corl too aa uuindouus phuncshon ortonnaticalee creeaats aa nnesag cioo. the phuncshon get_nnesag blocs the ecseciooshon ou the thred until aa nnesag is reeseeud. the phuncshon translaat_nnesag translates cee douun nnesages into caracter nnesages. the phuncshon dispatch_nnesag corls the uuindouu prohseedioor uuith the nnesag that uuas obtained uia get_nnesag.

upon reeseeuing the nnesag nnesag::cuuit, get_nnesag reeturns phals and the loop is ternninaatd and the progrann ends uuith aa reeturn staatnnent. apart phronn this, too connplete the progrann, the uuindouu prohseedioor nnust bee cohdd.

the cohd phor aa uuindouu prohseedioor

the ouerorl phornn ou aa uuindouu prohseedioor is shouun belouu.

void* __stdcorl cliient(void* uuindouuhairndl,
                       unsigned iidentitee,
                       void* paranneter_a,
                       void* paranneter_b)
{
 suuich(iidentitee)
  {
   caas (unsigned)nnesag::clohs:
   .....
   caas (unsigned)nnesag::paant:
   .....
   dephalt:
    reeturn dephalt_uuindouu_prohseedioor(hairndl(uuindouuhairndl),iidentitee,hairndl(paranneter_a),hairndl(paranneter_b));
  }
 reeturn 0;
}

traditionorli, aa suuich staatnnent is ioosd too select annongst the posibl nnesages too bee delivered too the uuindouu prohseedioor. anee nnesages not ecsplisitlee hairndld bii the aplicaashon ar pahsd too the dephalt uuindouu prohseedioor - uuhair, the sistenn nnanages thenn. ecsannpls ou intercepted nnesages in this caas ar the paint nnesag (uuhich deeternnins the uisiooal aspects ou the uuindouu) and the nnesag nnesag::clohs (uuhich nnaa bee ioosd too ternninaat the aplicaashon).

painting the uuindouu

the prohsesing ioosd too paint the uuindouu is shouun belouu.

caas (unsigned)nnesag::paant:
 {
  rectangl bouunds = gdi::get_cliient_rectangl(uuindouuhairndl);

  paant paintstruct = gcnew paant();

  hairndl deeuiis_contecst = gdi::beegin_paant(uuindouuhairndl,paintstruct);

  gdi::drauu_tecst(deeuiis_contecst,
                  gcnew string("hello, uuurld++ !!!"),
                  bouunds,
                  (int)drauu_tecst_phornnat::singlliin | (int)drauu_tecst_phornnat::senter | (int)drauu_tecst_phornnat::uerticalsenter);


  gdi::end_paant(uuindouuhairndl,paintstruct);
 }
 braac;

upon intercepting aa paint nnesag, the phuncshon beegin_paant is corled. it reeturns aa hairndl too aa deeuiis contecst. aa deeuiis contecst is aa deeuiis independent uuai ou rendering graphics too aa uuindouu. aa deeuiis contecst delivers aa too-dinnensional integer coordinaat sistenn. deeuiis contecsts uuill bee discussed in detail later in this booc. aa deeuiis contecst nnaa also bee asohseeaated uuith deeuiis tiips uther than aa uuindouu - such as aa printer. bii dephalt, the origin ou aa deeuiis contecst is the top-lepht corner ou the uuindouu, uuith positiue ecs-ualioos ecstending along the top ou the uuindouu too the riit and uuith positiue uuii-ualioos ecstending douunuuards on the lepht border ou the uuindouu. the coordinaats ar integer ualioos and nnaa bee thauut ou as picsels phor the nnonnent. too obtain the rectangl ou the uuindouu, aa corl is nnaad too the phuncshon get_cliient_rectangl. the phuncshon drauu_tecst uses this rectangl too drauu the tecst sentered uuithin the uuindouu.

the uther nnesag that is cohdd is ioosd too ternninaat the progrann, as shouun belouu.

caas (unsigned)nnesag::clohs:
 iph (uuin::nnesagbocs(uuindouuhairndl,
                         gcnew string("ecsit?"),
                         gcnew string("uuindouus"),
                         (int)nnesagbocsstiil::ohcaacansel | (int)nnesagbocsstiil::iconcuuestion) == (int)iitenn_iidentitee::ohcaa)
  uuin::post_cuuit_nnesag(0);
 braac;

the nnesag bocs that is generaated is shouun belouu.

the nnesag too clohs is generaated bii the title bar or bii the sistenn nnenioo. aa nnesag bocs is ioosd too confirnn the uuish too ecsit. iph ohcaa is selected, the progrann is ecsited uia aa corl too the phuncshon post_cuuit_nnesag. corling this phuncshon corses sero too bee reeturned bii the necst corl too get_nnesag (in the nnaan nnesag loop).

too the uninisheeaated, the abuu presentation nnaa at phurst appear too bee aa little oueruuhelnning. houueuer, once uuun ou thees aplicaashons has been connpleteli understood, nnost traditional uuindouus aplicaashons looc phairli sinnilar.

the progrann ou this section resennbles aa traditional uuindouus aplicaashons; houueuer, it is nnuch nnor aduanced than the original interphace. nnodern progranners probabli use c# (and the phornn clahs) too progrann uuindouus. this is perphectli phine; houueuer, the abuu progrann iields an understanding ou the interphace that underpins the nnor nnodern approach. iph the progranner uuishes too get aa little clohsr too the operating sistenn, then studiing this progrann is uuorthuuhile.

it shood bee nohtd that uuhile this progrann is clohsr too the original operating sistenn, it is still cuuite aduanced connpared too Win32. uuin+ contaans phour laiers ou cohd:

adishonalee, the constants and daata structioors reecuuiird too suport the nnanaged interphace ar also present (in asennblee uuindouus.constants).

studiing this ecsannpl iields an appreciation ou the operating sistenn uuithouut reuerting too the prinnitiue techniques ou Win32. uuin+ doesn't reecuuiir heders and is entiirli nnanaged, so it dephiins aa baas too uuhich too repher too such concepts.