editor_help.cpp 136 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271
  1. /**************************************************************************/
  2. /* editor_help.cpp */
  3. /**************************************************************************/
  4. /* This file is part of: */
  5. /* GODOT ENGINE */
  6. /* https://godotengine.org */
  7. /**************************************************************************/
  8. /* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
  9. /* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */
  10. /* */
  11. /* Permission is hereby granted, free of charge, to any person obtaining */
  12. /* a copy of this software and associated documentation files (the */
  13. /* "Software"), to deal in the Software without restriction, including */
  14. /* without limitation the rights to use, copy, modify, merge, publish, */
  15. /* distribute, sublicense, and/or sell copies of the Software, and to */
  16. /* permit persons to whom the Software is furnished to do so, subject to */
  17. /* the following conditions: */
  18. /* */
  19. /* The above copyright notice and this permission notice shall be */
  20. /* included in all copies or substantial portions of the Software. */
  21. /* */
  22. /* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */
  23. /* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */
  24. /* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
  25. /* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */
  26. /* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */
  27. /* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */
  28. /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */
  29. /**************************************************************************/
  30. #include "editor_help.h"
  31. #include "core/config/project_settings.h"
  32. #include "core/core_constants.h"
  33. #include "core/extension/gdextension.h"
  34. #include "core/input/input.h"
  35. #include "core/object/script_language.h"
  36. #include "core/os/keyboard.h"
  37. #include "core/string/string_builder.h"
  38. #include "core/version_generated.gen.h"
  39. #include "editor/doc_data_compressed.gen.h"
  40. #include "editor/editor_main_screen.h"
  41. #include "editor/editor_node.h"
  42. #include "editor/editor_paths.h"
  43. #include "editor/editor_property_name_processor.h"
  44. #include "editor/editor_settings.h"
  45. #include "editor/editor_string_names.h"
  46. #include "editor/plugins/script_editor_plugin.h"
  47. #include "editor/themes/editor_scale.h"
  48. #include "scene/gui/line_edit.h"
  49. #include "modules/modules_enabled.gen.h" // For gdscript, mono.
  50. // For syntax highlighting.
  51. #ifdef MODULE_GDSCRIPT_ENABLED
  52. #include "modules/gdscript/editor/gdscript_highlighter.h"
  53. #include "modules/gdscript/gdscript.h"
  54. #endif
  55. // For syntax highlighting.
  56. #ifdef MODULE_MONO_ENABLED
  57. #include "editor/plugins/script_editor_plugin.h"
  58. #include "modules/mono/csharp_script.h"
  59. #endif
  60. #define CONTRIBUTE_URL vformat("%s/contributing/documentation/updating_the_class_reference.html", VERSION_DOCS_URL)
  61. #ifdef MODULE_MONO_ENABLED
  62. // Sync with the types mentioned in https://docs.godotengine.org/en/stable/tutorials/scripting/c_sharp/c_sharp_differences.html
  63. const Vector<String> classes_with_csharp_differences = {
  64. "@GlobalScope",
  65. "String",
  66. "NodePath",
  67. "Signal",
  68. "Callable",
  69. "RID",
  70. "Basis",
  71. "Transform2D",
  72. "Transform3D",
  73. "Rect2",
  74. "Rect2i",
  75. "AABB",
  76. "Quaternion",
  77. "Projection",
  78. "Color",
  79. "Array",
  80. "Dictionary",
  81. "PackedByteArray",
  82. "PackedColorArray",
  83. "PackedFloat32Array",
  84. "PackedFloat64Array",
  85. "PackedInt32Array",
  86. "PackedInt64Array",
  87. "PackedStringArray",
  88. "PackedVector2Array",
  89. "PackedVector3Array",
  90. "PackedVector4Array",
  91. "Variant",
  92. };
  93. #endif
  94. const Vector<String> packed_array_types = {
  95. "PackedByteArray",
  96. "PackedColorArray",
  97. "PackedFloat32Array",
  98. "PackedFloat64Array",
  99. "PackedInt32Array",
  100. "PackedInt64Array",
  101. "PackedStringArray",
  102. "PackedVector2Array",
  103. "PackedVector3Array",
  104. "PackedVector4Array",
  105. };
  106. // TODO: this is sometimes used directly as doc->something, other times as EditorHelp::get_doc_data(), which is thread-safe.
  107. // Might this be a problem?
  108. DocTools *EditorHelp::doc = nullptr;
  109. DocTools *EditorHelp::ext_doc = nullptr;
  110. static bool _attempt_doc_load(const String &p_class) {
  111. // Docgen always happens in the outer-most class: it also generates docs for inner classes.
  112. String outer_class = p_class.get_slice(".", 0);
  113. if (!ScriptServer::is_global_class(outer_class)) {
  114. return false;
  115. }
  116. // ResourceLoader is used in order to have a script-agnostic way to load scripts.
  117. // This forces GDScript to compile the code, which is unnecessary for docgen, but it's a good compromise right now.
  118. Ref<Script> script = ResourceLoader::load(ScriptServer::get_global_class_path(outer_class), outer_class);
  119. if (script.is_valid()) {
  120. Vector<DocData::ClassDoc> docs = script->get_documentation();
  121. for (int j = 0; j < docs.size(); j++) {
  122. const DocData::ClassDoc &doc = docs.get(j);
  123. EditorHelp::get_doc_data()->add_doc(doc);
  124. }
  125. return true;
  126. }
  127. return false;
  128. }
  129. // Removes unnecessary prefix from p_class_specifier when within the p_edited_class context
  130. static String _contextualize_class_specifier(const String &p_class_specifier, const String &p_edited_class) {
  131. // If this is a completely different context than the current class, then keep full path
  132. if (!p_class_specifier.begins_with(p_edited_class)) {
  133. return p_class_specifier;
  134. }
  135. // Here equal length + begins_with from above implies p_class_specifier == p_edited_class :)
  136. if (p_class_specifier.length() == p_edited_class.length()) {
  137. int rfind = p_class_specifier.rfind_char('.');
  138. if (rfind == -1) { // Single identifier
  139. return p_class_specifier;
  140. }
  141. // Multiple specifiers: keep last one only
  142. return p_class_specifier.substr(rfind + 1);
  143. }
  144. // They share a _name_ prefix but not a _class specifier_ prefix, e.g. Tree & TreeItem
  145. // begins_with + lengths being different implies p_class_specifier.length() > p_edited_class.length() so this is safe
  146. if (p_class_specifier[p_edited_class.length()] != '.') {
  147. return p_class_specifier;
  148. }
  149. // Remove class specifier prefix
  150. return p_class_specifier.substr(p_edited_class.length() + 1);
  151. }
  152. void EditorHelp::_update_theme_item_cache() {
  153. VBoxContainer::_update_theme_item_cache();
  154. theme_cache.text_color = get_theme_color(SNAME("text_color"), SNAME("EditorHelp"));
  155. theme_cache.title_color = get_theme_color(SNAME("title_color"), SNAME("EditorHelp"));
  156. theme_cache.headline_color = get_theme_color(SNAME("headline_color"), SNAME("EditorHelp"));
  157. theme_cache.comment_color = get_theme_color(SNAME("comment_color"), SNAME("EditorHelp"));
  158. theme_cache.symbol_color = get_theme_color(SNAME("symbol_color"), SNAME("EditorHelp"));
  159. theme_cache.value_color = get_theme_color(SNAME("value_color"), SNAME("EditorHelp"));
  160. theme_cache.qualifier_color = get_theme_color(SNAME("qualifier_color"), SNAME("EditorHelp"));
  161. theme_cache.type_color = get_theme_color(SNAME("type_color"), SNAME("EditorHelp"));
  162. theme_cache.override_color = get_theme_color(SNAME("override_color"), SNAME("EditorHelp"));
  163. theme_cache.doc_font = get_theme_font(SNAME("doc"), EditorStringName(EditorFonts));
  164. theme_cache.doc_bold_font = get_theme_font(SNAME("doc_bold"), EditorStringName(EditorFonts));
  165. theme_cache.doc_italic_font = get_theme_font(SNAME("doc_italic"), EditorStringName(EditorFonts));
  166. theme_cache.doc_title_font = get_theme_font(SNAME("doc_title"), EditorStringName(EditorFonts));
  167. theme_cache.doc_code_font = get_theme_font(SNAME("doc_source"), EditorStringName(EditorFonts));
  168. theme_cache.doc_kbd_font = get_theme_font(SNAME("doc_keyboard"), EditorStringName(EditorFonts));
  169. theme_cache.doc_font_size = get_theme_font_size(SNAME("doc_size"), EditorStringName(EditorFonts));
  170. theme_cache.doc_title_font_size = get_theme_font_size(SNAME("doc_title_size"), EditorStringName(EditorFonts));
  171. theme_cache.doc_code_font_size = get_theme_font_size(SNAME("doc_source_size"), EditorStringName(EditorFonts));
  172. theme_cache.doc_kbd_font_size = get_theme_font_size(SNAME("doc_keyboard_size"), EditorStringName(EditorFonts));
  173. theme_cache.background_style = get_theme_stylebox(SNAME("background"), SNAME("EditorHelp"));
  174. class_desc->begin_bulk_theme_override();
  175. class_desc->add_theme_font_override("normal_font", theme_cache.doc_font);
  176. class_desc->add_theme_font_size_override("normal_font_size", theme_cache.doc_font_size);
  177. class_desc->add_theme_constant_override(SceneStringName(line_separation), get_theme_constant(SceneStringName(line_separation), SNAME("EditorHelp")));
  178. class_desc->add_theme_constant_override("table_h_separation", get_theme_constant(SNAME("table_h_separation"), SNAME("EditorHelp")));
  179. class_desc->add_theme_constant_override("table_v_separation", get_theme_constant(SNAME("table_v_separation"), SNAME("EditorHelp")));
  180. class_desc->add_theme_constant_override("text_highlight_h_padding", get_theme_constant(SNAME("text_highlight_h_padding"), SNAME("EditorHelp")));
  181. class_desc->add_theme_constant_override("text_highlight_v_padding", get_theme_constant(SNAME("text_highlight_v_padding"), SNAME("EditorHelp")));
  182. class_desc->end_bulk_theme_override();
  183. }
  184. void EditorHelp::_search(bool p_search_previous) {
  185. if (p_search_previous) {
  186. find_bar->search_prev();
  187. } else {
  188. find_bar->search_next();
  189. }
  190. }
  191. void EditorHelp::_class_desc_finished() {
  192. if (scroll_to >= 0) {
  193. class_desc->scroll_to_paragraph(scroll_to);
  194. }
  195. scroll_to = -1;
  196. }
  197. void EditorHelp::_class_list_select(const String &p_select) {
  198. _goto_desc(p_select);
  199. }
  200. void EditorHelp::_class_desc_select(const String &p_select) {
  201. if (p_select.begins_with("$")) { // Enum.
  202. const String link = p_select.substr(1);
  203. String enum_class_name;
  204. String enum_name;
  205. if (CoreConstants::is_global_enum(link)) {
  206. enum_class_name = "@GlobalScope";
  207. enum_name = link;
  208. } else {
  209. const int dot_pos = link.rfind_char('.');
  210. if (dot_pos >= 0) {
  211. enum_class_name = link.left(dot_pos);
  212. enum_name = link.substr(dot_pos + 1);
  213. } else {
  214. enum_class_name = edited_class;
  215. enum_name = link;
  216. }
  217. }
  218. emit_signal(SNAME("go_to_help"), "class_enum:" + enum_class_name + ":" + enum_name);
  219. } else if (p_select.begins_with("#")) { // Class.
  220. emit_signal(SNAME("go_to_help"), "class_name:" + p_select.substr(1));
  221. } else if (p_select.begins_with("@")) { // Member.
  222. const int tag_end = p_select.find_char(' ');
  223. const String tag = p_select.substr(1, tag_end - 1);
  224. const String link = p_select.substr(tag_end + 1).lstrip(" ");
  225. String topic;
  226. const HashMap<String, int> *table = nullptr;
  227. if (tag == "method") {
  228. topic = "class_method";
  229. table = &method_line;
  230. } else if (tag == "constructor") {
  231. topic = "class_method";
  232. table = &method_line;
  233. } else if (tag == "operator") {
  234. topic = "class_method";
  235. table = &method_line;
  236. } else if (tag == "member") {
  237. topic = "class_property";
  238. table = &property_line;
  239. } else if (tag == "enum") {
  240. topic = "class_enum";
  241. table = &enum_line;
  242. } else if (tag == "signal") {
  243. topic = "class_signal";
  244. table = &signal_line;
  245. } else if (tag == "constant") {
  246. topic = "class_constant";
  247. table = &constant_line;
  248. } else if (tag == "annotation") {
  249. topic = "class_annotation";
  250. table = &annotation_line;
  251. } else if (tag == "theme_item") {
  252. topic = "class_theme_item";
  253. table = &theme_property_line;
  254. } else {
  255. return;
  256. }
  257. // Case order is important here to correctly handle edge cases like Variant.Type in @GlobalScope.
  258. if (table->has(link)) {
  259. // Found in the current page.
  260. if (class_desc->is_finished()) {
  261. emit_signal(SNAME("request_save_history"));
  262. class_desc->scroll_to_paragraph((*table)[link]);
  263. } else {
  264. scroll_to = (*table)[link];
  265. }
  266. } else {
  267. // Look for link in @GlobalScope.
  268. // Note that a link like @GlobalScope.enum_name will not be found in this section, only enum_name will be.
  269. if (topic == "class_enum") {
  270. const DocData::ClassDoc &cd = doc->class_list["@GlobalScope"];
  271. for (const DocData::ConstantDoc &constant : cd.constants) {
  272. if (constant.enumeration == link) {
  273. // Found in @GlobalScope.
  274. emit_signal(SNAME("go_to_help"), topic + ":@GlobalScope:" + link);
  275. return;
  276. }
  277. }
  278. } else if (topic == "class_constant") {
  279. const DocData::ClassDoc &cd = doc->class_list["@GlobalScope"];
  280. for (const DocData::ConstantDoc &constant : cd.constants) {
  281. if (constant.name == link) {
  282. // Found in @GlobalScope.
  283. emit_signal(SNAME("go_to_help"), topic + ":@GlobalScope:" + link);
  284. return;
  285. }
  286. }
  287. }
  288. if (link.contains_char('.')) {
  289. const int class_end = link.find_char('.');
  290. emit_signal(SNAME("go_to_help"), topic + ":" + link.left(class_end) + ":" + link.substr(class_end + 1));
  291. }
  292. }
  293. } else if (p_select.begins_with("http:") || p_select.begins_with("https:")) {
  294. OS::get_singleton()->shell_open(p_select);
  295. } else if (p_select.begins_with("^")) { // Copy button.
  296. DisplayServer::get_singleton()->clipboard_set(p_select.substr(1));
  297. }
  298. }
  299. void EditorHelp::_class_desc_input(const Ref<InputEvent> &p_input) {
  300. }
  301. void EditorHelp::_class_desc_resized(bool p_force_update_theme) {
  302. // Add extra horizontal margins for better readability.
  303. // The margins increase as the width of the editor help container increases.
  304. real_t char_width = theme_cache.doc_code_font->get_char_size('x', theme_cache.doc_code_font_size).width;
  305. const int new_display_margin = MAX(30 * EDSCALE, get_parent_anchorable_rect().size.width - char_width * 120 * EDSCALE) * 0.5;
  306. if (display_margin != new_display_margin || p_force_update_theme) {
  307. display_margin = new_display_margin;
  308. Ref<StyleBox> class_desc_stylebox = theme_cache.background_style->duplicate();
  309. class_desc_stylebox->set_content_margin(SIDE_LEFT, display_margin);
  310. class_desc_stylebox->set_content_margin(SIDE_RIGHT, display_margin);
  311. class_desc->add_theme_style_override(CoreStringName(normal), class_desc_stylebox);
  312. class_desc->add_theme_style_override("focused", class_desc_stylebox);
  313. }
  314. }
  315. static void _add_type_to_rt(const String &p_type, const String &p_enum, bool p_is_bitfield, RichTextLabel *p_rt, const Control *p_owner_node, const String &p_class) {
  316. const Color type_color = p_owner_node->get_theme_color(SNAME("type_color"), SNAME("EditorHelp"));
  317. if (p_type.is_empty() || p_type == "void") {
  318. p_rt->push_color(Color(type_color, 0.5));
  319. p_rt->push_hint(TTR("No return value."));
  320. p_rt->add_text("void");
  321. p_rt->pop(); // hint
  322. p_rt->pop(); // color
  323. return;
  324. }
  325. bool is_enum_type = !p_enum.is_empty();
  326. bool is_bitfield = p_is_bitfield && is_enum_type;
  327. bool can_ref = !p_type.contains_char('*') || is_enum_type;
  328. String link_t = p_type; // For links in metadata
  329. String display_t; // For display purposes.
  330. if (is_enum_type) {
  331. link_t = p_enum; // The link for enums is always the full enum description
  332. display_t = _contextualize_class_specifier(p_enum, p_class);
  333. } else {
  334. display_t = _contextualize_class_specifier(p_type, p_class);
  335. }
  336. p_rt->push_color(type_color);
  337. bool add_typed_container = false;
  338. if (can_ref) {
  339. if (link_t.ends_with("[]")) {
  340. add_typed_container = true;
  341. link_t = link_t.trim_suffix("[]");
  342. display_t = display_t.trim_suffix("[]");
  343. p_rt->push_meta("#Array", RichTextLabel::META_UNDERLINE_ON_HOVER); // class
  344. p_rt->add_text("Array");
  345. p_rt->pop(); // meta
  346. p_rt->add_text("[");
  347. } else if (link_t.begins_with("Dictionary[")) {
  348. add_typed_container = true;
  349. link_t = link_t.trim_prefix("Dictionary[").trim_suffix("]");
  350. display_t = display_t.trim_prefix("Dictionary[").trim_suffix("]");
  351. p_rt->push_meta("#Dictionary", RichTextLabel::META_UNDERLINE_ON_HOVER); // class
  352. p_rt->add_text("Dictionary");
  353. p_rt->pop(); // meta
  354. p_rt->add_text("[");
  355. p_rt->push_meta("#" + link_t.get_slice(", ", 0), RichTextLabel::META_UNDERLINE_ON_HOVER); // class
  356. p_rt->add_text(_contextualize_class_specifier(display_t.get_slice(", ", 0), p_class));
  357. p_rt->pop(); // meta
  358. p_rt->add_text(", ");
  359. link_t = link_t.get_slice(", ", 1);
  360. display_t = _contextualize_class_specifier(display_t.get_slice(", ", 1), p_class);
  361. } else if (is_bitfield) {
  362. p_rt->push_color(Color(type_color, 0.5));
  363. p_rt->push_hint(TTR("This value is an integer composed as a bitmask of the following flags."));
  364. p_rt->add_text("BitField");
  365. p_rt->pop(); // hint
  366. p_rt->add_text("[");
  367. p_rt->pop(); // color
  368. }
  369. if (is_enum_type) {
  370. p_rt->push_meta("$" + link_t, RichTextLabel::META_UNDERLINE_ON_HOVER); // enum
  371. } else {
  372. p_rt->push_meta("#" + link_t, RichTextLabel::META_UNDERLINE_ON_HOVER); // class
  373. }
  374. }
  375. p_rt->add_text(display_t);
  376. if (can_ref) {
  377. p_rt->pop(); // meta
  378. if (add_typed_container) {
  379. p_rt->add_text("]");
  380. } else if (is_bitfield) {
  381. p_rt->push_color(Color(type_color, 0.5));
  382. p_rt->add_text("]");
  383. p_rt->pop(); // color
  384. }
  385. }
  386. p_rt->pop(); // color
  387. }
  388. void EditorHelp::_add_type(const String &p_type, const String &p_enum, bool p_is_bitfield) {
  389. _add_type_to_rt(p_type, p_enum, p_is_bitfield, class_desc, this, edited_class);
  390. }
  391. void EditorHelp::_add_type_icon(const String &p_type, int p_size, const String &p_fallback) {
  392. Ref<Texture2D> icon = EditorNode::get_singleton()->get_class_icon(p_type, p_fallback);
  393. Vector2i size = Vector2i(icon->get_width(), icon->get_height());
  394. if (p_size > 0) {
  395. // Ensures icon scales proportionally on both axes, based on icon height.
  396. float ratio = p_size / float(size.height);
  397. size.width *= ratio;
  398. size.height *= ratio;
  399. }
  400. class_desc->add_image(icon, size.width, size.height);
  401. }
  402. String EditorHelp::_fix_constant(const String &p_constant) const {
  403. if (p_constant.strip_edges() == "4294967295") {
  404. return "0xFFFFFFFF";
  405. }
  406. if (p_constant.strip_edges() == "2147483647") {
  407. return "0x7FFFFFFF";
  408. }
  409. if (p_constant.strip_edges() == "1048575") {
  410. return "0xFFFFF";
  411. }
  412. return p_constant;
  413. }
  414. // Macros for assigning the deprecated/experimental marks to class members in overview.
  415. #define DEPRECATED_DOC_TAG \
  416. class_desc->push_font(theme_cache.doc_bold_font); \
  417. class_desc->push_color(get_theme_color(SNAME("error_color"), EditorStringName(Editor))); \
  418. Ref<Texture2D> error_icon = get_editor_theme_icon(SNAME("StatusError")); \
  419. class_desc->add_image(error_icon, error_icon->get_width(), error_icon->get_height()); \
  420. class_desc->add_text(String::chr(160) + TTR("Deprecated")); \
  421. class_desc->pop(); \
  422. class_desc->pop();
  423. #define EXPERIMENTAL_DOC_TAG \
  424. class_desc->push_font(theme_cache.doc_bold_font); \
  425. class_desc->push_color(get_theme_color(SNAME("warning_color"), EditorStringName(Editor))); \
  426. Ref<Texture2D> warning_icon = get_editor_theme_icon(SNAME("NodeWarning")); \
  427. class_desc->add_image(warning_icon, warning_icon->get_width(), warning_icon->get_height()); \
  428. class_desc->add_text(String::chr(160) + TTR("Experimental")); \
  429. class_desc->pop(); \
  430. class_desc->pop();
  431. // Macros for displaying the deprecated/experimental info in class member descriptions.
  432. #define DEPRECATED_DOC_MSG(m_message, m_default_message) \
  433. Ref<Texture2D> error_icon = get_editor_theme_icon(SNAME("StatusError")); \
  434. class_desc->add_image(error_icon, error_icon->get_width(), error_icon->get_height()); \
  435. class_desc->add_text(" "); \
  436. class_desc->push_color(get_theme_color(SNAME("error_color"), EditorStringName(Editor))); \
  437. class_desc->push_font(theme_cache.doc_bold_font); \
  438. class_desc->add_text(TTR("Deprecated:")); \
  439. class_desc->pop(); \
  440. class_desc->pop(); \
  441. class_desc->add_text(" "); \
  442. if ((m_message).is_empty()) { \
  443. class_desc->add_text(m_default_message); \
  444. } else { \
  445. _add_text(m_message); \
  446. }
  447. #define EXPERIMENTAL_DOC_MSG(m_message, m_default_message) \
  448. Ref<Texture2D> warning_icon = get_editor_theme_icon(SNAME("NodeWarning")); \
  449. class_desc->add_image(warning_icon, warning_icon->get_width(), warning_icon->get_height()); \
  450. class_desc->add_text(" "); \
  451. class_desc->push_color(get_theme_color(SNAME("warning_color"), EditorStringName(Editor))); \
  452. class_desc->push_font(theme_cache.doc_bold_font); \
  453. class_desc->add_text(TTR("Experimental:")); \
  454. class_desc->pop(); \
  455. class_desc->pop(); \
  456. class_desc->add_text(" "); \
  457. if ((m_message).is_empty()) { \
  458. class_desc->add_text(m_default_message); \
  459. } else { \
  460. _add_text(m_message); \
  461. }
  462. void EditorHelp::_add_method(const DocData::MethodDoc &p_method, bool p_overview, bool p_override) {
  463. if (p_override) {
  464. method_line[p_method.name] = class_desc->get_paragraph_count() - 2; // Gets overridden if description.
  465. }
  466. const bool is_vararg = p_method.qualifiers.contains("vararg");
  467. if (p_overview) {
  468. class_desc->push_cell();
  469. class_desc->push_paragraph(HORIZONTAL_ALIGNMENT_RIGHT, Control::TEXT_DIRECTION_AUTO, "");
  470. } else {
  471. _add_bulletpoint();
  472. }
  473. _add_type(p_method.return_type, p_method.return_enum, p_method.return_is_bitfield);
  474. if (p_overview) {
  475. class_desc->pop(); // paragraph
  476. class_desc->pop(); // cell
  477. class_desc->push_cell();
  478. } else {
  479. class_desc->add_text(" ");
  480. }
  481. const bool is_documented = p_method.is_deprecated || p_method.is_experimental || !p_method.description.strip_edges().is_empty();
  482. if (p_overview && is_documented) {
  483. class_desc->push_meta("@method " + p_method.name, RichTextLabel::META_UNDERLINE_ON_HOVER);
  484. }
  485. class_desc->push_color(theme_cache.headline_color);
  486. class_desc->add_text(p_method.name);
  487. class_desc->pop(); // color
  488. if (p_overview && is_documented) {
  489. class_desc->pop(); // meta
  490. }
  491. class_desc->push_color(theme_cache.symbol_color);
  492. class_desc->add_text("(");
  493. class_desc->pop(); // color
  494. for (int j = 0; j < p_method.arguments.size(); j++) {
  495. const DocData::ArgumentDoc &argument = p_method.arguments[j];
  496. class_desc->push_color(theme_cache.text_color);
  497. if (j > 0) {
  498. class_desc->add_text(", ");
  499. }
  500. class_desc->add_text(argument.name);
  501. class_desc->add_text(": ");
  502. _add_type(argument.type, argument.enumeration, argument.is_bitfield);
  503. if (!argument.default_value.is_empty()) {
  504. class_desc->push_color(theme_cache.symbol_color);
  505. class_desc->add_text(" = ");
  506. class_desc->pop(); // color
  507. class_desc->push_color(theme_cache.value_color);
  508. class_desc->add_text(_fix_constant(argument.default_value));
  509. class_desc->pop(); // color
  510. }
  511. class_desc->pop(); // color
  512. }
  513. if (is_vararg) {
  514. class_desc->push_color(theme_cache.text_color);
  515. if (!p_method.arguments.is_empty()) {
  516. class_desc->add_text(", ");
  517. }
  518. class_desc->pop(); // color
  519. class_desc->push_color(theme_cache.symbol_color);
  520. class_desc->add_text("...");
  521. class_desc->pop(); // color
  522. }
  523. class_desc->push_color(theme_cache.symbol_color);
  524. class_desc->add_text(")");
  525. class_desc->pop(); // color
  526. if (!p_method.qualifiers.is_empty()) {
  527. class_desc->push_color(theme_cache.qualifier_color);
  528. PackedStringArray qualifiers = p_method.qualifiers.split_spaces();
  529. for (const String &qualifier : qualifiers) {
  530. String hint;
  531. if (qualifier == "vararg") {
  532. hint = TTR("This method supports a variable number of arguments.");
  533. } else if (qualifier == "virtual") {
  534. hint = TTR("This method is called by the engine.\nIt can be overridden to customize built-in behavior.");
  535. } else if (qualifier == "const") {
  536. hint = TTR("This method has no side effects.\nIt does not modify the object in any way.");
  537. } else if (qualifier == "static") {
  538. hint = TTR("This method does not need an instance to be called.\nIt can be called directly using the class name.");
  539. }
  540. class_desc->add_text(" ");
  541. if (!hint.is_empty()) {
  542. class_desc->push_hint(hint);
  543. class_desc->add_text(qualifier);
  544. class_desc->pop(); // hint
  545. } else {
  546. class_desc->add_text(qualifier);
  547. }
  548. }
  549. class_desc->pop(); // color
  550. }
  551. if (p_overview) {
  552. if (p_method.is_deprecated) {
  553. class_desc->add_text(" ");
  554. DEPRECATED_DOC_TAG;
  555. }
  556. if (p_method.is_experimental) {
  557. class_desc->add_text(" ");
  558. EXPERIMENTAL_DOC_TAG;
  559. }
  560. class_desc->pop(); // cell
  561. }
  562. }
  563. void EditorHelp::_add_bulletpoint() {
  564. static const char32_t prefix[3] = { 0x25CF /* filled circle */, ' ', 0 };
  565. class_desc->add_text(String(prefix));
  566. }
  567. void EditorHelp::_push_normal_font() {
  568. class_desc->push_font(theme_cache.doc_font);
  569. class_desc->push_font_size(theme_cache.doc_font_size);
  570. }
  571. void EditorHelp::_pop_normal_font() {
  572. class_desc->pop(); // font_size
  573. class_desc->pop(); // font
  574. }
  575. void EditorHelp::_push_title_font() {
  576. class_desc->push_font(theme_cache.doc_title_font);
  577. class_desc->push_font_size(theme_cache.doc_title_font_size);
  578. class_desc->push_color(theme_cache.title_color);
  579. }
  580. void EditorHelp::_pop_title_font() {
  581. class_desc->pop(); // color
  582. class_desc->pop(); // font_size
  583. class_desc->pop(); // font
  584. }
  585. void EditorHelp::_push_code_font() {
  586. class_desc->push_font(theme_cache.doc_code_font);
  587. class_desc->push_font_size(theme_cache.doc_code_font_size);
  588. }
  589. void EditorHelp::_pop_code_font() {
  590. class_desc->pop(); // font_size
  591. class_desc->pop(); // font
  592. }
  593. Error EditorHelp::_goto_desc(const String &p_class) {
  594. // If class doesn't have docs listed, attempt on-demand docgen
  595. if (!doc->class_list.has(p_class) && !_attempt_doc_load(p_class)) {
  596. return ERR_DOES_NOT_EXIST;
  597. }
  598. select_locked = true;
  599. class_desc->show();
  600. description_line = 0;
  601. if (p_class == edited_class) {
  602. return OK; // Already there.
  603. }
  604. edited_class = p_class;
  605. _update_doc();
  606. return OK;
  607. }
  608. void EditorHelp::_update_method_list(MethodType p_method_type, const Vector<DocData::MethodDoc> &p_methods) {
  609. class_desc->add_newline();
  610. class_desc->add_newline();
  611. static const char *titles_by_type[METHOD_TYPE_MAX] = {
  612. TTRC("Methods"),
  613. TTRC("Constructors"),
  614. TTRC("Operators"),
  615. };
  616. const String title = TTRGET(titles_by_type[p_method_type]);
  617. section_line.push_back(Pair<String, int>(title, class_desc->get_paragraph_count() - 2));
  618. _push_title_font();
  619. class_desc->add_text(title);
  620. _pop_title_font();
  621. class_desc->add_newline();
  622. class_desc->add_newline();
  623. class_desc->push_indent(1);
  624. _push_code_font();
  625. class_desc->push_table(2);
  626. class_desc->set_table_column_expand(1, true);
  627. bool any_previous = false;
  628. for (int pass = 0; pass < 2; pass++) {
  629. Vector<DocData::MethodDoc> m;
  630. for (const DocData::MethodDoc &method : p_methods) {
  631. const String &q = method.qualifiers;
  632. if ((pass == 0 && q.contains("virtual")) || (pass == 1 && !q.contains("virtual"))) {
  633. m.push_back(method);
  634. }
  635. }
  636. if (any_previous && !m.is_empty()) {
  637. class_desc->push_cell();
  638. class_desc->pop(); // cell
  639. class_desc->push_cell();
  640. class_desc->pop(); // cell
  641. }
  642. String group_prefix;
  643. for (int i = 0; i < m.size(); i++) {
  644. const String new_prefix = m[i].name.left(3);
  645. bool is_new_group = false;
  646. if (i < m.size() - 1 && new_prefix == m[i + 1].name.left(3) && new_prefix != group_prefix) {
  647. is_new_group = i > 0;
  648. group_prefix = new_prefix;
  649. } else if (!group_prefix.is_empty() && new_prefix != group_prefix) {
  650. is_new_group = true;
  651. group_prefix = "";
  652. }
  653. if (is_new_group && pass == 1) {
  654. class_desc->push_cell();
  655. class_desc->pop(); // cell
  656. class_desc->push_cell();
  657. class_desc->pop(); // cell
  658. }
  659. // For constructors always point to the first one.
  660. _add_method(m[i], true, (p_method_type != METHOD_TYPE_CONSTRUCTOR || i == 0));
  661. }
  662. any_previous = !m.is_empty();
  663. }
  664. class_desc->pop(); // table
  665. _pop_code_font();
  666. class_desc->pop(); // indent
  667. }
  668. void EditorHelp::_update_method_descriptions(const DocData::ClassDoc &p_classdoc, MethodType p_method_type, const Vector<DocData::MethodDoc> &p_methods) {
  669. #define HANDLE_DOC(m_string) ((p_classdoc.is_script_doc ? (m_string) : DTR(m_string)).strip_edges())
  670. class_desc->add_newline();
  671. class_desc->add_newline();
  672. class_desc->add_newline();
  673. static const char *titles_by_type[METHOD_TYPE_MAX] = {
  674. TTRC("Method Descriptions"),
  675. TTRC("Constructor Descriptions"),
  676. TTRC("Operator Descriptions"),
  677. };
  678. const String title = TTRGET(titles_by_type[p_method_type]);
  679. section_line.push_back(Pair<String, int>(title, class_desc->get_paragraph_count() - 2));
  680. _push_title_font();
  681. class_desc->add_text(title);
  682. _pop_title_font();
  683. String link_color_text = theme_cache.title_color.to_html(false);
  684. for (int pass = 0; pass < 2; pass++) {
  685. Vector<DocData::MethodDoc> methods_filtered;
  686. for (int i = 0; i < p_methods.size(); i++) {
  687. const String &q = p_methods[i].qualifiers;
  688. if ((pass == 0 && q.contains("virtual")) || (pass == 1 && !q.contains("virtual"))) {
  689. methods_filtered.push_back(p_methods[i]);
  690. }
  691. }
  692. for (int i = 0; i < methods_filtered.size(); i++) {
  693. const DocData::MethodDoc &method = methods_filtered[i];
  694. class_desc->add_newline();
  695. class_desc->add_newline();
  696. class_desc->add_newline();
  697. _push_code_font();
  698. // For constructors always point to the first one.
  699. _add_method(method, false, (p_method_type != METHOD_TYPE_CONSTRUCTOR || i == 0));
  700. _pop_code_font();
  701. class_desc->add_newline();
  702. class_desc->add_newline();
  703. class_desc->push_indent(1);
  704. _push_normal_font();
  705. class_desc->push_color(theme_cache.text_color);
  706. bool has_prev_text = false;
  707. if (method.is_deprecated) {
  708. has_prev_text = true;
  709. static const char *messages_by_type[METHOD_TYPE_MAX] = {
  710. TTRC("This method may be changed or removed in future versions."),
  711. TTRC("This constructor may be changed or removed in future versions."),
  712. TTRC("This operator may be changed or removed in future versions."),
  713. };
  714. DEPRECATED_DOC_MSG(HANDLE_DOC(method.deprecated_message), TTRGET(messages_by_type[p_method_type]));
  715. }
  716. if (method.is_experimental) {
  717. if (has_prev_text) {
  718. class_desc->add_newline();
  719. class_desc->add_newline();
  720. }
  721. has_prev_text = true;
  722. static const char *messages_by_type[METHOD_TYPE_MAX] = {
  723. TTRC("This method may be changed or removed in future versions."),
  724. TTRC("This constructor may be changed or removed in future versions."),
  725. TTRC("This operator may be changed or removed in future versions."),
  726. };
  727. EXPERIMENTAL_DOC_MSG(HANDLE_DOC(method.experimental_message), TTRGET(messages_by_type[p_method_type]));
  728. }
  729. if (!method.errors_returned.is_empty()) {
  730. if (has_prev_text) {
  731. class_desc->add_newline();
  732. class_desc->add_newline();
  733. }
  734. has_prev_text = true;
  735. class_desc->add_text(TTR("Error codes returned:"));
  736. class_desc->add_newline();
  737. class_desc->push_list(0, RichTextLabel::LIST_DOTS, false);
  738. for (int j = 0; j < method.errors_returned.size(); j++) {
  739. if (j > 0) {
  740. class_desc->add_newline();
  741. }
  742. int val = method.errors_returned[j];
  743. String text = itos(val);
  744. for (int k = 0; k < CoreConstants::get_global_constant_count(); k++) {
  745. if (CoreConstants::get_global_constant_value(k) == val && CoreConstants::get_global_constant_enum(k) == SNAME("Error")) {
  746. text = CoreConstants::get_global_constant_name(k);
  747. break;
  748. }
  749. }
  750. class_desc->push_font(theme_cache.doc_bold_font);
  751. class_desc->add_text(text);
  752. class_desc->pop(); // font
  753. }
  754. class_desc->pop(); // list
  755. }
  756. const String descr = HANDLE_DOC(method.description);
  757. const bool is_documented = method.is_deprecated || method.is_experimental || !descr.is_empty();
  758. if (!descr.is_empty()) {
  759. if (has_prev_text) {
  760. class_desc->add_newline();
  761. class_desc->add_newline();
  762. }
  763. has_prev_text = true;
  764. _add_text(descr);
  765. } else if (!is_documented) {
  766. if (has_prev_text) {
  767. class_desc->add_newline();
  768. class_desc->add_newline();
  769. }
  770. has_prev_text = true;
  771. String message;
  772. if (p_classdoc.is_script_doc) {
  773. static const char *messages_by_type[METHOD_TYPE_MAX] = {
  774. TTRC("There is currently no description for this method."),
  775. TTRC("There is currently no description for this constructor."),
  776. TTRC("There is currently no description for this operator."),
  777. };
  778. message = TTRGET(messages_by_type[p_method_type]);
  779. } else {
  780. static const char *messages_by_type[METHOD_TYPE_MAX] = {
  781. TTRC("There is currently no description for this method. Please help us by [color=$color][url=$url]contributing one[/url][/color]!"),
  782. TTRC("There is currently no description for this constructor. Please help us by [color=$color][url=$url]contributing one[/url][/color]!"),
  783. TTRC("There is currently no description for this operator. Please help us by [color=$color][url=$url]contributing one[/url][/color]!"),
  784. };
  785. message = TTRGET(messages_by_type[p_method_type]).replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text);
  786. }
  787. class_desc->add_image(get_editor_theme_icon(SNAME("Error")));
  788. class_desc->add_text(" ");
  789. class_desc->push_color(theme_cache.comment_color);
  790. class_desc->append_text(message);
  791. class_desc->pop(); // color
  792. }
  793. class_desc->pop(); // color
  794. _pop_normal_font();
  795. class_desc->pop(); // indent
  796. }
  797. }
  798. #undef HANDLE_DOC
  799. }
  800. void EditorHelp::_update_doc() {
  801. if (!doc->class_list.has(edited_class)) {
  802. return;
  803. }
  804. scroll_locked = true;
  805. class_desc->clear();
  806. method_line.clear();
  807. section_line.clear();
  808. section_line.push_back(Pair<String, int>(TTR("Top"), 0));
  809. String link_color_text = theme_cache.title_color.to_html(false);
  810. DocData::ClassDoc cd = doc->class_list[edited_class]; // Make a copy, so we can sort without worrying.
  811. #define HANDLE_DOC(m_string) ((cd.is_script_doc ? (m_string) : DTR(m_string)).strip_edges())
  812. // Class name
  813. _push_title_font();
  814. class_desc->add_text(TTR("Class:") + " ");
  815. _add_type_icon(edited_class, theme_cache.doc_title_font_size, "Object");
  816. class_desc->add_text(" ");
  817. class_desc->push_color(theme_cache.headline_color);
  818. class_desc->add_text(edited_class);
  819. class_desc->pop(); // color
  820. _pop_title_font();
  821. if (cd.is_deprecated) {
  822. class_desc->add_newline();
  823. DEPRECATED_DOC_MSG(HANDLE_DOC(cd.deprecated_message), TTR("This class may be changed or removed in future versions."));
  824. }
  825. if (cd.is_experimental) {
  826. class_desc->add_newline();
  827. EXPERIMENTAL_DOC_MSG(HANDLE_DOC(cd.experimental_message), TTR("This class may be changed or removed in future versions."));
  828. }
  829. // Inheritance tree
  830. const String non_breaking_space = String::chr(160);
  831. // Ascendents
  832. if (!cd.inherits.is_empty()) {
  833. class_desc->add_newline();
  834. _push_normal_font();
  835. class_desc->push_color(theme_cache.title_color);
  836. class_desc->add_text(TTR("Inherits:") + " ");
  837. String inherits = cd.inherits;
  838. while (!inherits.is_empty()) {
  839. _add_type_icon(inherits, theme_cache.doc_font_size, "ArrowRight");
  840. class_desc->add_text(non_breaking_space); // Otherwise icon borrows hyperlink from _add_type().
  841. _add_type(inherits);
  842. inherits = doc->class_list[inherits].inherits;
  843. if (!inherits.is_empty()) {
  844. class_desc->add_text(" < ");
  845. }
  846. }
  847. class_desc->pop(); // color
  848. _pop_normal_font();
  849. }
  850. // Descendants
  851. if ((cd.is_script_doc || ClassDB::class_exists(cd.name)) && doc->inheriting.has(cd.name)) {
  852. class_desc->add_newline();
  853. _push_normal_font();
  854. class_desc->push_color(theme_cache.title_color);
  855. class_desc->add_text(TTR("Inherited by:") + " ");
  856. for (RBSet<String, NaturalNoCaseComparator>::Element *itr = doc->inheriting[cd.name].front(); itr; itr = itr->next()) {
  857. if (itr->prev()) {
  858. class_desc->add_text(" , ");
  859. }
  860. _add_type_icon(itr->get(), theme_cache.doc_font_size, "ArrowRight");
  861. class_desc->add_text(non_breaking_space); // Otherwise icon borrows hyperlink from _add_type().
  862. _add_type(itr->get());
  863. }
  864. class_desc->pop(); // color
  865. _pop_normal_font();
  866. }
  867. bool has_description = false;
  868. // Brief description
  869. const String brief_class_descr = HANDLE_DOC(cd.brief_description);
  870. if (!brief_class_descr.is_empty()) {
  871. has_description = true;
  872. class_desc->add_newline();
  873. class_desc->add_newline();
  874. class_desc->push_indent(1);
  875. class_desc->push_font(theme_cache.doc_bold_font);
  876. class_desc->push_color(theme_cache.text_color);
  877. _add_text(brief_class_descr);
  878. class_desc->pop(); // color
  879. class_desc->pop(); // font
  880. class_desc->pop(); // indent
  881. }
  882. // Class description
  883. const String class_descr = HANDLE_DOC(cd.description);
  884. if (!class_descr.is_empty()) {
  885. has_description = true;
  886. class_desc->add_newline();
  887. class_desc->add_newline();
  888. section_line.push_back(Pair<String, int>(TTR("Description"), class_desc->get_paragraph_count() - 2));
  889. description_line = class_desc->get_paragraph_count() - 2;
  890. _push_title_font();
  891. class_desc->add_text(TTR("Description"));
  892. _pop_title_font();
  893. class_desc->add_newline();
  894. class_desc->add_newline();
  895. class_desc->push_indent(1);
  896. _push_normal_font();
  897. class_desc->push_color(theme_cache.text_color);
  898. _add_text(class_descr);
  899. class_desc->pop(); // color
  900. _pop_normal_font();
  901. class_desc->pop(); // indent
  902. }
  903. if (!has_description) {
  904. class_desc->add_newline();
  905. class_desc->add_newline();
  906. class_desc->push_indent(1);
  907. _push_normal_font();
  908. class_desc->add_image(get_editor_theme_icon(SNAME("Error")));
  909. class_desc->add_text(" ");
  910. class_desc->push_color(theme_cache.comment_color);
  911. if (cd.is_script_doc) {
  912. class_desc->add_text(TTR("There is currently no description for this class."));
  913. } else {
  914. class_desc->append_text(TTR("There is currently no description for this class. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text));
  915. }
  916. class_desc->pop(); // color
  917. _pop_normal_font();
  918. class_desc->pop(); // indent
  919. }
  920. #ifdef MODULE_MONO_ENABLED
  921. if (classes_with_csharp_differences.has(cd.name)) {
  922. class_desc->add_newline();
  923. class_desc->add_newline();
  924. const String &csharp_differences_url = vformat("%s/tutorials/scripting/c_sharp/c_sharp_differences.html", VERSION_DOCS_URL);
  925. class_desc->push_indent(1);
  926. _push_normal_font();
  927. class_desc->push_color(theme_cache.text_color);
  928. class_desc->append_text("[b]" + TTR("Note:") + "[/b] " + vformat(TTR("There are notable differences when using this API with C#. See [url=%s]C# API differences to GDScript[/url] for more information."), csharp_differences_url));
  929. class_desc->pop(); // color
  930. _pop_normal_font();
  931. class_desc->pop(); // indent
  932. }
  933. #endif
  934. // Online tutorials
  935. if (!cd.tutorials.is_empty()) {
  936. class_desc->add_newline();
  937. class_desc->add_newline();
  938. _push_title_font();
  939. class_desc->add_text(TTR("Online Tutorials"));
  940. _pop_title_font();
  941. class_desc->add_newline();
  942. class_desc->push_indent(1);
  943. _push_code_font();
  944. class_desc->push_color(theme_cache.symbol_color);
  945. for (const DocData::TutorialDoc &tutorial : cd.tutorials) {
  946. const String link = HANDLE_DOC(tutorial.link);
  947. String link_text = HANDLE_DOC(tutorial.title);
  948. if (link_text.is_empty()) {
  949. const int sep_pos = link.find("//");
  950. if (sep_pos >= 0) {
  951. link_text = link.substr(sep_pos + 2);
  952. } else {
  953. link_text = link;
  954. }
  955. }
  956. class_desc->add_newline();
  957. _add_bulletpoint();
  958. class_desc->append_text("[url=" + link + "]" + link_text + "[/url]");
  959. }
  960. class_desc->pop(); // color
  961. _pop_code_font();
  962. class_desc->pop(); // indent
  963. }
  964. // Properties overview
  965. HashSet<String> skip_methods;
  966. bool has_properties = false;
  967. bool has_property_descriptions = false;
  968. for (const DocData::PropertyDoc &prop : cd.properties) {
  969. const bool is_documented = prop.is_deprecated || prop.is_experimental || !prop.description.strip_edges().is_empty();
  970. if (!is_documented && prop.name.begins_with("_")) {
  971. continue;
  972. }
  973. has_properties = true;
  974. if (!prop.overridden) {
  975. has_property_descriptions = true;
  976. break;
  977. }
  978. }
  979. if (has_properties) {
  980. class_desc->add_newline();
  981. class_desc->add_newline();
  982. section_line.push_back(Pair<String, int>(TTR("Properties"), class_desc->get_paragraph_count() - 2));
  983. _push_title_font();
  984. class_desc->add_text(TTR("Properties"));
  985. _pop_title_font();
  986. class_desc->add_newline();
  987. class_desc->add_newline();
  988. class_desc->push_indent(1);
  989. _push_code_font();
  990. class_desc->push_table(4);
  991. class_desc->set_table_column_expand(1, true);
  992. cd.properties.sort_custom<PropertyCompare>();
  993. bool is_generating_overridden_properties = true; // Set to false as soon as we encounter a non-overridden property.
  994. bool overridden_property_exists = false;
  995. for (const DocData::PropertyDoc &prop : cd.properties) {
  996. // Ignore undocumented private.
  997. const bool is_documented = prop.is_deprecated || prop.is_experimental || !prop.description.strip_edges().is_empty();
  998. if (!is_documented && prop.name.begins_with("_")) {
  999. continue;
  1000. }
  1001. if (is_generating_overridden_properties && !prop.overridden) {
  1002. is_generating_overridden_properties = false;
  1003. // No need for the extra spacing when there's no overridden property.
  1004. if (overridden_property_exists) {
  1005. class_desc->push_cell();
  1006. class_desc->pop(); // cell
  1007. class_desc->push_cell();
  1008. class_desc->pop(); // cell
  1009. class_desc->push_cell();
  1010. class_desc->pop(); // cell
  1011. class_desc->push_cell();
  1012. class_desc->pop(); // cell
  1013. }
  1014. }
  1015. property_line[prop.name] = class_desc->get_paragraph_count() - 2; // Gets overridden if description.
  1016. // Property type.
  1017. class_desc->push_cell();
  1018. class_desc->push_paragraph(HORIZONTAL_ALIGNMENT_RIGHT, Control::TEXT_DIRECTION_AUTO, "");
  1019. _add_type(prop.type, prop.enumeration, prop.is_bitfield);
  1020. class_desc->pop(); // paragraph
  1021. class_desc->pop(); // cell
  1022. bool describe = false;
  1023. if (!prop.setter.is_empty()) {
  1024. skip_methods.insert(prop.setter);
  1025. describe = true;
  1026. }
  1027. if (!prop.getter.is_empty()) {
  1028. skip_methods.insert(prop.getter);
  1029. describe = true;
  1030. }
  1031. if (is_documented) {
  1032. describe = true;
  1033. }
  1034. if (prop.overridden) {
  1035. describe = false;
  1036. }
  1037. // Property name.
  1038. class_desc->push_cell();
  1039. class_desc->push_color(theme_cache.headline_color);
  1040. if (describe) {
  1041. class_desc->push_meta("@member " + prop.name, RichTextLabel::META_UNDERLINE_ON_HOVER);
  1042. }
  1043. class_desc->add_text(prop.name);
  1044. if (describe) {
  1045. class_desc->pop(); // meta
  1046. }
  1047. class_desc->pop(); // color
  1048. class_desc->pop(); // cell
  1049. // Property value.
  1050. class_desc->push_cell();
  1051. if (!prop.default_value.is_empty()) {
  1052. if (prop.overridden) {
  1053. class_desc->push_color(theme_cache.override_color);
  1054. class_desc->add_text("[");
  1055. const String link = vformat("[url=@member %s.%s]%s[/url]", prop.overrides, prop.name, prop.overrides);
  1056. class_desc->append_text(vformat(TTR("overrides %s:"), link));
  1057. class_desc->add_text(" " + _fix_constant(prop.default_value) + "]");
  1058. class_desc->pop(); // color
  1059. overridden_property_exists = true;
  1060. } else {
  1061. class_desc->push_color(theme_cache.symbol_color);
  1062. class_desc->add_text("[" + TTR("default:") + " ");
  1063. class_desc->pop(); // color
  1064. class_desc->push_color(theme_cache.value_color);
  1065. class_desc->add_text(_fix_constant(prop.default_value));
  1066. class_desc->pop(); // color
  1067. class_desc->push_color(theme_cache.symbol_color);
  1068. class_desc->add_text("]");
  1069. class_desc->pop(); // color
  1070. }
  1071. }
  1072. class_desc->pop(); // cell
  1073. // Property setter/getter and deprecated/experimental marks.
  1074. class_desc->push_cell();
  1075. bool has_prev_text = false;
  1076. if (cd.is_script_doc && (!prop.setter.is_empty() || !prop.getter.is_empty())) {
  1077. has_prev_text = true;
  1078. class_desc->push_color(theme_cache.symbol_color);
  1079. class_desc->add_text("[" + TTR("property:") + " ");
  1080. class_desc->pop(); // color
  1081. if (!prop.setter.is_empty()) {
  1082. class_desc->push_color(theme_cache.value_color);
  1083. class_desc->add_text("setter");
  1084. class_desc->pop(); // color
  1085. }
  1086. if (!prop.getter.is_empty()) {
  1087. if (!prop.setter.is_empty()) {
  1088. class_desc->push_color(theme_cache.symbol_color);
  1089. class_desc->add_text(", ");
  1090. class_desc->pop(); // color
  1091. }
  1092. class_desc->push_color(theme_cache.value_color);
  1093. class_desc->add_text("getter");
  1094. class_desc->pop(); // color
  1095. }
  1096. class_desc->push_color(theme_cache.symbol_color);
  1097. class_desc->add_text("]");
  1098. class_desc->pop(); // color
  1099. }
  1100. if (prop.is_deprecated) {
  1101. if (has_prev_text) {
  1102. class_desc->add_text(" ");
  1103. }
  1104. has_prev_text = true;
  1105. DEPRECATED_DOC_TAG;
  1106. }
  1107. if (prop.is_experimental) {
  1108. if (has_prev_text) {
  1109. class_desc->add_text(" ");
  1110. }
  1111. has_prev_text = true;
  1112. EXPERIMENTAL_DOC_TAG;
  1113. }
  1114. class_desc->pop(); // cell
  1115. }
  1116. class_desc->pop(); // table
  1117. _pop_code_font();
  1118. class_desc->pop(); // indent
  1119. }
  1120. // Methods overview
  1121. bool sort_methods = EDITOR_GET("text_editor/help/sort_functions_alphabetically");
  1122. Vector<DocData::MethodDoc> methods;
  1123. for (const DocData::MethodDoc &method : cd.methods) {
  1124. if (skip_methods.has(method.name)) {
  1125. if (method.arguments.is_empty() /* getter */ || (method.arguments.size() == 1 && method.return_type == "void" /* setter */)) {
  1126. continue;
  1127. }
  1128. }
  1129. // Ignore undocumented non virtual private.
  1130. const bool is_documented = method.is_deprecated || method.is_experimental || !method.description.strip_edges().is_empty();
  1131. if (!is_documented && method.name.begins_with("_") && !method.qualifiers.contains("virtual")) {
  1132. continue;
  1133. }
  1134. methods.push_back(method);
  1135. }
  1136. if (!cd.constructors.is_empty()) {
  1137. if (sort_methods) {
  1138. cd.constructors.sort();
  1139. }
  1140. _update_method_list(METHOD_TYPE_CONSTRUCTOR, cd.constructors);
  1141. }
  1142. if (!methods.is_empty()) {
  1143. if (sort_methods) {
  1144. methods.sort();
  1145. }
  1146. _update_method_list(METHOD_TYPE_METHOD, methods);
  1147. }
  1148. if (!cd.operators.is_empty()) {
  1149. if (sort_methods) {
  1150. cd.operators.sort();
  1151. }
  1152. _update_method_list(METHOD_TYPE_OPERATOR, cd.operators);
  1153. }
  1154. // Theme properties
  1155. if (!cd.theme_properties.is_empty()) {
  1156. class_desc->add_newline();
  1157. class_desc->add_newline();
  1158. section_line.push_back(Pair<String, int>(TTR("Theme Properties"), class_desc->get_paragraph_count() - 2));
  1159. _push_title_font();
  1160. class_desc->add_text(TTR("Theme Properties"));
  1161. _pop_title_font();
  1162. String theme_data_type;
  1163. HashMap<String, String> data_type_names;
  1164. data_type_names["color"] = TTR("Colors");
  1165. data_type_names["constant"] = TTR("Constants");
  1166. data_type_names["font"] = TTR("Fonts");
  1167. data_type_names["font_size"] = TTR("Font Sizes");
  1168. data_type_names["icon"] = TTR("Icons");
  1169. data_type_names["style"] = TTR("Styles");
  1170. for (const DocData::ThemeItemDoc &theme_item : cd.theme_properties) {
  1171. if (theme_data_type != theme_item.data_type) {
  1172. theme_data_type = theme_item.data_type;
  1173. class_desc->add_newline();
  1174. class_desc->add_newline();
  1175. class_desc->push_indent(1);
  1176. _push_title_font();
  1177. if (data_type_names.has(theme_data_type)) {
  1178. class_desc->add_text(data_type_names[theme_data_type]);
  1179. } else {
  1180. class_desc->add_text(theme_data_type);
  1181. }
  1182. _pop_title_font();
  1183. class_desc->pop(); // indent
  1184. }
  1185. class_desc->add_newline();
  1186. class_desc->add_newline();
  1187. theme_property_line[theme_item.name] = class_desc->get_paragraph_count() - 2; // Gets overridden if description.
  1188. class_desc->push_indent(1);
  1189. // Theme item header.
  1190. _push_code_font();
  1191. _add_bulletpoint();
  1192. // Theme item object type.
  1193. _add_type(theme_item.type);
  1194. // Theme item name.
  1195. class_desc->push_color(theme_cache.headline_color);
  1196. class_desc->add_text(" ");
  1197. class_desc->add_text(theme_item.name);
  1198. class_desc->pop(); // color
  1199. // Theme item default value.
  1200. if (!theme_item.default_value.is_empty()) {
  1201. class_desc->push_color(theme_cache.symbol_color);
  1202. class_desc->add_text(" [" + TTR("default:") + " ");
  1203. class_desc->pop(); // color
  1204. class_desc->push_color(theme_cache.value_color);
  1205. class_desc->add_text(_fix_constant(theme_item.default_value));
  1206. class_desc->pop(); // color
  1207. class_desc->push_color(theme_cache.symbol_color);
  1208. class_desc->add_text("]");
  1209. class_desc->pop(); // color
  1210. }
  1211. _pop_code_font();
  1212. // Theme item description.
  1213. class_desc->push_indent(1);
  1214. _push_normal_font();
  1215. class_desc->push_color(theme_cache.comment_color);
  1216. bool has_prev_text = false;
  1217. if (theme_item.is_deprecated) {
  1218. has_prev_text = true;
  1219. DEPRECATED_DOC_MSG(HANDLE_DOC(theme_item.deprecated_message), TTR("This theme property may be changed or removed in future versions."));
  1220. }
  1221. if (theme_item.is_experimental) {
  1222. if (has_prev_text) {
  1223. class_desc->add_newline();
  1224. class_desc->add_newline();
  1225. }
  1226. has_prev_text = true;
  1227. EXPERIMENTAL_DOC_MSG(HANDLE_DOC(theme_item.experimental_message), TTR("This theme property may be changed or removed in future versions."));
  1228. }
  1229. const String descr = HANDLE_DOC(theme_item.description);
  1230. if (!descr.is_empty()) {
  1231. if (has_prev_text) {
  1232. class_desc->add_newline();
  1233. class_desc->add_newline();
  1234. }
  1235. has_prev_text = true;
  1236. _add_text(descr);
  1237. } else if (!has_prev_text) {
  1238. class_desc->add_image(get_editor_theme_icon(SNAME("Error")));
  1239. class_desc->add_text(" ");
  1240. class_desc->push_color(theme_cache.comment_color);
  1241. if (cd.is_script_doc) {
  1242. class_desc->add_text(TTR("There is currently no description for this theme property."));
  1243. } else {
  1244. class_desc->append_text(TTR("There is currently no description for this theme property. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text));
  1245. }
  1246. class_desc->pop(); // color
  1247. }
  1248. class_desc->pop(); // color
  1249. _pop_normal_font();
  1250. class_desc->pop(); // indent
  1251. class_desc->pop(); // indent
  1252. }
  1253. }
  1254. // Signals
  1255. if (!cd.signals.is_empty()) {
  1256. if (sort_methods) {
  1257. cd.signals.sort();
  1258. }
  1259. class_desc->add_newline();
  1260. class_desc->add_newline();
  1261. section_line.push_back(Pair<String, int>(TTR("Signals"), class_desc->get_paragraph_count() - 2));
  1262. _push_title_font();
  1263. class_desc->add_text(TTR("Signals"));
  1264. _pop_title_font();
  1265. for (const DocData::MethodDoc &signal : cd.signals) {
  1266. class_desc->add_newline();
  1267. class_desc->add_newline();
  1268. signal_line[signal.name] = class_desc->get_paragraph_count() - 2; // Gets overridden if description.
  1269. class_desc->push_indent(1);
  1270. // Signal header.
  1271. _push_code_font();
  1272. _add_bulletpoint();
  1273. class_desc->push_color(theme_cache.headline_color);
  1274. class_desc->add_text(signal.name);
  1275. class_desc->pop(); // color
  1276. class_desc->push_color(theme_cache.symbol_color);
  1277. class_desc->add_text("(");
  1278. class_desc->pop(); // color
  1279. for (int j = 0; j < signal.arguments.size(); j++) {
  1280. const DocData::ArgumentDoc &argument = signal.arguments[j];
  1281. class_desc->push_color(theme_cache.text_color);
  1282. if (j > 0) {
  1283. class_desc->add_text(", ");
  1284. }
  1285. class_desc->add_text(argument.name);
  1286. class_desc->add_text(": ");
  1287. _add_type(argument.type, argument.enumeration, argument.is_bitfield);
  1288. // Signals currently do not support default argument values, neither the core nor GDScript.
  1289. // This code is just for completeness.
  1290. if (!argument.default_value.is_empty()) {
  1291. class_desc->push_color(theme_cache.symbol_color);
  1292. class_desc->add_text(" = ");
  1293. class_desc->pop(); // color
  1294. class_desc->push_color(theme_cache.value_color);
  1295. class_desc->add_text(_fix_constant(argument.default_value));
  1296. class_desc->pop(); // color
  1297. }
  1298. class_desc->pop(); // color
  1299. }
  1300. class_desc->push_color(theme_cache.symbol_color);
  1301. class_desc->add_text(")");
  1302. class_desc->pop(); // color
  1303. _pop_code_font();
  1304. class_desc->add_newline();
  1305. // Signal description.
  1306. class_desc->push_indent(1);
  1307. _push_normal_font();
  1308. class_desc->push_color(theme_cache.comment_color);
  1309. const String descr = HANDLE_DOC(signal.description);
  1310. const bool is_multiline = descr.find_char('\n') > 0;
  1311. bool has_prev_text = false;
  1312. if (signal.is_deprecated) {
  1313. has_prev_text = true;
  1314. DEPRECATED_DOC_MSG(HANDLE_DOC(signal.deprecated_message), TTR("This signal may be changed or removed in future versions."));
  1315. }
  1316. if (signal.is_experimental) {
  1317. if (has_prev_text) {
  1318. class_desc->add_newline();
  1319. if (is_multiline) {
  1320. class_desc->add_newline();
  1321. }
  1322. }
  1323. has_prev_text = true;
  1324. EXPERIMENTAL_DOC_MSG(HANDLE_DOC(signal.experimental_message), TTR("This signal may be changed or removed in future versions."));
  1325. }
  1326. if (!descr.is_empty()) {
  1327. if (has_prev_text) {
  1328. class_desc->add_newline();
  1329. if (is_multiline) {
  1330. class_desc->add_newline();
  1331. }
  1332. }
  1333. has_prev_text = true;
  1334. _add_text(descr);
  1335. } else if (!has_prev_text) {
  1336. class_desc->add_image(get_editor_theme_icon(SNAME("Error")));
  1337. class_desc->add_text(" ");
  1338. class_desc->push_color(theme_cache.comment_color);
  1339. if (cd.is_script_doc) {
  1340. class_desc->add_text(TTR("There is currently no description for this signal."));
  1341. } else {
  1342. class_desc->append_text(TTR("There is currently no description for this signal. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text));
  1343. }
  1344. class_desc->pop(); // color
  1345. }
  1346. class_desc->pop(); // color
  1347. _pop_normal_font();
  1348. class_desc->pop(); // indent
  1349. class_desc->pop(); // indent
  1350. }
  1351. }
  1352. // Constants and enums
  1353. if (!cd.constants.is_empty()) {
  1354. HashMap<String, Vector<DocData::ConstantDoc>> enums;
  1355. Vector<DocData::ConstantDoc> constants;
  1356. for (const DocData::ConstantDoc &constant : cd.constants) {
  1357. if (!constant.enumeration.is_empty()) {
  1358. if (!enums.has(constant.enumeration)) {
  1359. enums[constant.enumeration] = Vector<DocData::ConstantDoc>();
  1360. }
  1361. enums[constant.enumeration].push_back(constant);
  1362. } else {
  1363. // Ignore undocumented private.
  1364. const bool is_documented = constant.is_deprecated || constant.is_experimental || !constant.description.strip_edges().is_empty();
  1365. if (!is_documented && constant.name.begins_with("_")) {
  1366. continue;
  1367. }
  1368. constants.push_back(constant);
  1369. }
  1370. }
  1371. // Enums
  1372. bool has_enums = enums.size() && !cd.is_script_doc;
  1373. if (enums.size() && !has_enums) {
  1374. for (KeyValue<String, DocData::EnumDoc> &E : cd.enums) {
  1375. const bool is_documented = E.value.is_deprecated || E.value.is_experimental || !E.value.description.strip_edges().is_empty();
  1376. if (!is_documented && E.key.begins_with("_")) {
  1377. continue;
  1378. }
  1379. has_enums = true;
  1380. break;
  1381. }
  1382. }
  1383. if (has_enums) {
  1384. class_desc->add_newline();
  1385. class_desc->add_newline();
  1386. section_line.push_back(Pair<String, int>(TTR("Enumerations"), class_desc->get_paragraph_count() - 2));
  1387. _push_title_font();
  1388. class_desc->add_text(TTR("Enumerations"));
  1389. _pop_title_font();
  1390. for (KeyValue<String, Vector<DocData::ConstantDoc>> &E : enums) {
  1391. String key = E.key;
  1392. if ((key.get_slice_count(".") > 1) && (key.get_slice(".", 0) == edited_class)) {
  1393. key = key.get_slice(".", 1);
  1394. }
  1395. if (cd.enums.has(key)) {
  1396. const bool is_documented = cd.enums[key].is_deprecated || cd.enums[key].is_experimental || !cd.enums[key].description.strip_edges().is_empty();
  1397. if (!is_documented && cd.is_script_doc && E.key.begins_with("_")) {
  1398. continue;
  1399. }
  1400. }
  1401. class_desc->add_newline();
  1402. class_desc->add_newline();
  1403. // Enum header.
  1404. _push_code_font();
  1405. enum_line[E.key] = class_desc->get_paragraph_count() - 2;
  1406. class_desc->push_color(theme_cache.title_color);
  1407. if (E.value.size() && E.value[0].is_bitfield) {
  1408. class_desc->add_text("flags ");
  1409. } else {
  1410. class_desc->add_text("enum ");
  1411. }
  1412. class_desc->pop(); // color
  1413. class_desc->push_color(theme_cache.headline_color);
  1414. class_desc->add_text(key);
  1415. class_desc->pop(); // color
  1416. class_desc->push_color(theme_cache.symbol_color);
  1417. class_desc->add_text(":");
  1418. class_desc->pop(); // color
  1419. _pop_code_font();
  1420. // Enum description.
  1421. if (key != "@unnamed_enums" && cd.enums.has(key)) {
  1422. const String descr = HANDLE_DOC(cd.enums[key].description);
  1423. const bool is_multiline = descr.find_char('\n') > 0;
  1424. if (cd.enums[key].is_deprecated || cd.enums[key].is_experimental || !descr.is_empty()) {
  1425. class_desc->add_newline();
  1426. class_desc->push_indent(1);
  1427. _push_normal_font();
  1428. class_desc->push_color(theme_cache.text_color);
  1429. bool has_prev_text = false;
  1430. if (cd.enums[key].is_deprecated) {
  1431. has_prev_text = true;
  1432. DEPRECATED_DOC_MSG(HANDLE_DOC(cd.enums[key].deprecated_message), TTR("This enumeration may be changed or removed in future versions."));
  1433. }
  1434. if (cd.enums[key].is_experimental) {
  1435. if (has_prev_text) {
  1436. class_desc->add_newline();
  1437. if (is_multiline) {
  1438. class_desc->add_newline();
  1439. }
  1440. }
  1441. has_prev_text = true;
  1442. EXPERIMENTAL_DOC_MSG(HANDLE_DOC(cd.enums[key].experimental_message), TTR("This enumeration may be changed or removed in future versions."));
  1443. }
  1444. if (!descr.is_empty()) {
  1445. if (has_prev_text) {
  1446. class_desc->add_newline();
  1447. if (is_multiline) {
  1448. class_desc->add_newline();
  1449. }
  1450. }
  1451. has_prev_text = true;
  1452. _add_text(descr);
  1453. }
  1454. class_desc->pop(); // color
  1455. _pop_normal_font();
  1456. class_desc->pop(); // indent
  1457. }
  1458. }
  1459. HashMap<String, int> enum_values;
  1460. const int enum_start_line = enum_line[E.key];
  1461. bool prev_is_multiline = true; // Use a large margin for the first item.
  1462. for (const DocData::ConstantDoc &enum_value : E.value) {
  1463. const String descr = HANDLE_DOC(enum_value.description);
  1464. const bool is_multiline = descr.find_char('\n') > 0;
  1465. class_desc->add_newline();
  1466. if (prev_is_multiline || is_multiline) {
  1467. class_desc->add_newline();
  1468. }
  1469. prev_is_multiline = is_multiline;
  1470. if (cd.name == "@GlobalScope") {
  1471. enum_values[enum_value.name] = enum_start_line;
  1472. }
  1473. // Add the enum constant line to the constant_line map so we can locate it as a constant.
  1474. constant_line[enum_value.name] = class_desc->get_paragraph_count() - 2;
  1475. class_desc->push_indent(1);
  1476. // Enum value header.
  1477. _push_code_font();
  1478. _add_bulletpoint();
  1479. class_desc->push_color(theme_cache.headline_color);
  1480. class_desc->add_text(enum_value.name);
  1481. class_desc->pop(); // color
  1482. class_desc->push_color(theme_cache.symbol_color);
  1483. class_desc->add_text(" = ");
  1484. class_desc->pop(); // color
  1485. class_desc->push_color(theme_cache.value_color);
  1486. class_desc->add_text(_fix_constant(enum_value.value));
  1487. class_desc->pop(); // color
  1488. _pop_code_font();
  1489. // Enum value description.
  1490. if (enum_value.is_deprecated || enum_value.is_experimental || !descr.is_empty()) {
  1491. class_desc->add_newline();
  1492. class_desc->push_indent(1);
  1493. _push_normal_font();
  1494. class_desc->push_color(theme_cache.comment_color);
  1495. bool has_prev_text = false;
  1496. if (enum_value.is_deprecated) {
  1497. has_prev_text = true;
  1498. DEPRECATED_DOC_MSG(HANDLE_DOC(enum_value.deprecated_message), TTR("This constant may be changed or removed in future versions."));
  1499. }
  1500. if (enum_value.is_experimental) {
  1501. if (has_prev_text) {
  1502. class_desc->add_newline();
  1503. if (is_multiline) {
  1504. class_desc->add_newline();
  1505. }
  1506. }
  1507. has_prev_text = true;
  1508. EXPERIMENTAL_DOC_MSG(HANDLE_DOC(enum_value.experimental_message), TTR("This constant may be changed or removed in future versions."));
  1509. }
  1510. if (!descr.is_empty()) {
  1511. if (has_prev_text) {
  1512. class_desc->add_newline();
  1513. if (is_multiline) {
  1514. class_desc->add_newline();
  1515. }
  1516. }
  1517. has_prev_text = true;
  1518. _add_text(descr);
  1519. }
  1520. class_desc->pop(); // color
  1521. _pop_normal_font();
  1522. class_desc->pop(); // indent
  1523. }
  1524. class_desc->pop(); // indent
  1525. }
  1526. if (cd.name == "@GlobalScope") {
  1527. enum_values_line[E.key] = enum_values;
  1528. }
  1529. }
  1530. }
  1531. // Constants
  1532. if (!constants.is_empty()) {
  1533. class_desc->add_newline();
  1534. class_desc->add_newline();
  1535. section_line.push_back(Pair<String, int>(TTR("Constants"), class_desc->get_paragraph_count() - 2));
  1536. _push_title_font();
  1537. class_desc->add_text(TTR("Constants"));
  1538. _pop_title_font();
  1539. bool prev_is_multiline = true; // Use a large margin for the first item.
  1540. for (const DocData::ConstantDoc &constant : constants) {
  1541. const String descr = HANDLE_DOC(constant.description);
  1542. const bool is_multiline = descr.find_char('\n') > 0;
  1543. class_desc->add_newline();
  1544. if (prev_is_multiline || is_multiline) {
  1545. class_desc->add_newline();
  1546. }
  1547. prev_is_multiline = is_multiline;
  1548. constant_line[constant.name] = class_desc->get_paragraph_count() - 2;
  1549. class_desc->push_indent(1);
  1550. // Constant header.
  1551. _push_code_font();
  1552. if (constant.value.begins_with("Color(") && constant.value.ends_with(")")) {
  1553. String stripped = constant.value.replace(" ", "").replace("Color(", "").replace(")", "");
  1554. PackedFloat64Array color = stripped.split_floats(",");
  1555. if (color.size() >= 3) {
  1556. class_desc->push_color(Color(color[0], color[1], color[2]));
  1557. _add_bulletpoint();
  1558. class_desc->pop(); // color
  1559. }
  1560. } else {
  1561. _add_bulletpoint();
  1562. }
  1563. class_desc->push_color(theme_cache.headline_color);
  1564. class_desc->add_text(constant.name);
  1565. class_desc->pop(); // color
  1566. class_desc->push_color(theme_cache.symbol_color);
  1567. class_desc->add_text(" = ");
  1568. class_desc->pop(); // color
  1569. class_desc->push_color(theme_cache.value_color);
  1570. class_desc->add_text(_fix_constant(constant.value));
  1571. class_desc->pop(); // color
  1572. _pop_code_font();
  1573. // Constant description.
  1574. if (constant.is_deprecated || constant.is_experimental || !descr.is_empty()) {
  1575. class_desc->add_newline();
  1576. class_desc->push_indent(1);
  1577. _push_normal_font();
  1578. class_desc->push_color(theme_cache.comment_color);
  1579. bool has_prev_text = false;
  1580. if (constant.is_deprecated) {
  1581. has_prev_text = true;
  1582. DEPRECATED_DOC_MSG(HANDLE_DOC(constant.deprecated_message), TTR("This constant may be changed or removed in future versions."));
  1583. }
  1584. if (constant.is_experimental) {
  1585. if (has_prev_text) {
  1586. class_desc->add_newline();
  1587. if (is_multiline) {
  1588. class_desc->add_newline();
  1589. }
  1590. }
  1591. has_prev_text = true;
  1592. EXPERIMENTAL_DOC_MSG(HANDLE_DOC(constant.experimental_message), TTR("This constant may be changed or removed in future versions."));
  1593. }
  1594. if (!descr.is_empty()) {
  1595. if (has_prev_text) {
  1596. class_desc->add_newline();
  1597. if (is_multiline) {
  1598. class_desc->add_newline();
  1599. }
  1600. }
  1601. has_prev_text = true;
  1602. _add_text(descr);
  1603. }
  1604. class_desc->pop(); // color
  1605. _pop_normal_font();
  1606. class_desc->pop(); // indent
  1607. }
  1608. class_desc->pop(); // indent
  1609. }
  1610. }
  1611. }
  1612. // Annotations
  1613. if (!cd.annotations.is_empty()) {
  1614. if (sort_methods) {
  1615. cd.annotations.sort();
  1616. }
  1617. class_desc->add_newline();
  1618. class_desc->add_newline();
  1619. section_line.push_back(Pair<String, int>(TTR("Annotations"), class_desc->get_paragraph_count() - 2));
  1620. _push_title_font();
  1621. class_desc->add_text(TTR("Annotations"));
  1622. _pop_title_font();
  1623. for (const DocData::MethodDoc &annotation : cd.annotations) {
  1624. class_desc->add_newline();
  1625. class_desc->add_newline();
  1626. annotation_line[annotation.name] = class_desc->get_paragraph_count() - 2; // Gets overridden if description.
  1627. class_desc->push_indent(1);
  1628. // Annotation header.
  1629. _push_code_font();
  1630. _add_bulletpoint();
  1631. class_desc->push_color(theme_cache.headline_color);
  1632. class_desc->add_text(annotation.name);
  1633. class_desc->pop(); // color
  1634. if (!annotation.arguments.is_empty()) {
  1635. class_desc->push_color(theme_cache.symbol_color);
  1636. class_desc->add_text("(");
  1637. class_desc->pop(); // color
  1638. for (int j = 0; j < annotation.arguments.size(); j++) {
  1639. const DocData::ArgumentDoc &argument = annotation.arguments[j];
  1640. class_desc->push_color(theme_cache.text_color);
  1641. if (j > 0) {
  1642. class_desc->add_text(", ");
  1643. }
  1644. class_desc->add_text(argument.name);
  1645. class_desc->add_text(": ");
  1646. _add_type(argument.type, argument.enumeration, argument.is_bitfield);
  1647. if (!argument.default_value.is_empty()) {
  1648. class_desc->push_color(theme_cache.symbol_color);
  1649. class_desc->add_text(" = ");
  1650. class_desc->pop(); // color
  1651. class_desc->push_color(theme_cache.value_color);
  1652. class_desc->add_text(_fix_constant(argument.default_value));
  1653. class_desc->pop(); // color
  1654. }
  1655. class_desc->pop(); // color
  1656. }
  1657. if (annotation.qualifiers.contains("vararg")) {
  1658. class_desc->push_color(theme_cache.text_color);
  1659. if (!annotation.arguments.is_empty()) {
  1660. class_desc->add_text(", ");
  1661. }
  1662. class_desc->pop(); // color
  1663. class_desc->push_color(theme_cache.symbol_color);
  1664. class_desc->add_text("...");
  1665. class_desc->pop(); // color
  1666. }
  1667. class_desc->push_color(theme_cache.symbol_color);
  1668. class_desc->add_text(")");
  1669. class_desc->pop(); // color
  1670. }
  1671. if (!annotation.qualifiers.is_empty()) {
  1672. class_desc->push_color(theme_cache.qualifier_color);
  1673. class_desc->add_text(" ");
  1674. class_desc->add_text(annotation.qualifiers);
  1675. class_desc->pop(); // color
  1676. }
  1677. _pop_code_font();
  1678. class_desc->add_newline();
  1679. // Annotation description.
  1680. class_desc->push_indent(1);
  1681. _push_normal_font();
  1682. class_desc->push_color(theme_cache.comment_color);
  1683. const String descr = HANDLE_DOC(annotation.description);
  1684. if (!descr.is_empty()) {
  1685. _add_text(descr);
  1686. } else {
  1687. class_desc->add_image(get_editor_theme_icon(SNAME("Error")));
  1688. class_desc->add_text(" ");
  1689. class_desc->push_color(theme_cache.comment_color);
  1690. if (cd.is_script_doc) {
  1691. class_desc->add_text(TTR("There is currently no description for this annotation."));
  1692. } else {
  1693. class_desc->append_text(TTR("There is currently no description for this annotation. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text));
  1694. }
  1695. class_desc->pop(); // color
  1696. }
  1697. class_desc->pop(); // color
  1698. _pop_normal_font();
  1699. class_desc->pop(); // indent
  1700. class_desc->pop(); // indent
  1701. }
  1702. }
  1703. // Property descriptions
  1704. if (has_property_descriptions) {
  1705. class_desc->add_newline();
  1706. class_desc->add_newline();
  1707. class_desc->add_newline();
  1708. section_line.push_back(Pair<String, int>(TTR("Property Descriptions"), class_desc->get_paragraph_count() - 2));
  1709. _push_title_font();
  1710. class_desc->add_text(TTR("Property Descriptions"));
  1711. _pop_title_font();
  1712. for (const DocData::PropertyDoc &prop : cd.properties) {
  1713. if (prop.overridden) {
  1714. continue;
  1715. }
  1716. // Ignore undocumented private.
  1717. const bool is_documented = prop.is_deprecated || prop.is_experimental || !prop.description.strip_edges().is_empty();
  1718. if (!is_documented && prop.name.begins_with("_")) {
  1719. continue;
  1720. }
  1721. class_desc->add_newline();
  1722. class_desc->add_newline();
  1723. class_desc->add_newline();
  1724. property_line[prop.name] = class_desc->get_paragraph_count() - 2;
  1725. class_desc->push_table(2);
  1726. class_desc->set_table_column_expand(1, true);
  1727. class_desc->push_cell();
  1728. _push_code_font();
  1729. _add_bulletpoint();
  1730. _add_type(prop.type, prop.enumeration, prop.is_bitfield);
  1731. _pop_code_font();
  1732. class_desc->pop(); // cell
  1733. class_desc->push_cell();
  1734. _push_code_font();
  1735. class_desc->push_color(theme_cache.headline_color);
  1736. class_desc->add_text(prop.name);
  1737. class_desc->pop(); // color
  1738. if (!prop.default_value.is_empty()) {
  1739. class_desc->push_color(theme_cache.symbol_color);
  1740. class_desc->add_text(" [" + TTR("default:") + " ");
  1741. class_desc->pop(); // color
  1742. class_desc->push_color(theme_cache.value_color);
  1743. class_desc->add_text(_fix_constant(prop.default_value));
  1744. class_desc->pop(); // color
  1745. class_desc->push_color(theme_cache.symbol_color);
  1746. class_desc->add_text("]");
  1747. class_desc->pop(); // color
  1748. }
  1749. if (cd.is_script_doc && (!prop.setter.is_empty() || !prop.getter.is_empty())) {
  1750. class_desc->push_color(theme_cache.symbol_color);
  1751. class_desc->add_text(" [" + TTR("property:") + " ");
  1752. class_desc->pop(); // color
  1753. if (!prop.setter.is_empty()) {
  1754. class_desc->push_color(theme_cache.value_color);
  1755. class_desc->add_text("setter");
  1756. class_desc->pop(); // color
  1757. }
  1758. if (!prop.getter.is_empty()) {
  1759. if (!prop.setter.is_empty()) {
  1760. class_desc->push_color(theme_cache.symbol_color);
  1761. class_desc->add_text(", ");
  1762. class_desc->pop(); // color
  1763. }
  1764. class_desc->push_color(theme_cache.value_color);
  1765. class_desc->add_text("getter");
  1766. class_desc->pop(); // color
  1767. }
  1768. class_desc->push_color(theme_cache.symbol_color);
  1769. class_desc->add_text("]");
  1770. class_desc->pop(); // color
  1771. }
  1772. _pop_code_font();
  1773. class_desc->pop(); // cell
  1774. // Script doc doesn't have setter, getter.
  1775. if (!cd.is_script_doc) {
  1776. HashMap<String, DocData::MethodDoc> method_map;
  1777. for (int j = 0; j < methods.size(); j++) {
  1778. method_map[methods[j].name] = methods[j];
  1779. }
  1780. if (!prop.setter.is_empty()) {
  1781. class_desc->push_cell();
  1782. class_desc->pop(); // cell
  1783. class_desc->push_cell();
  1784. _push_code_font();
  1785. class_desc->push_color(theme_cache.text_color);
  1786. if (method_map[prop.setter].arguments.size() > 1) {
  1787. // Setters with additional arguments are exposed in the method list, so we link them here for quick access.
  1788. class_desc->push_meta("@method " + prop.setter);
  1789. class_desc->add_text(prop.setter + TTR("(value)"));
  1790. class_desc->pop(); // meta
  1791. } else {
  1792. class_desc->add_text(prop.setter + TTR("(value)"));
  1793. }
  1794. class_desc->pop(); // color
  1795. class_desc->push_color(theme_cache.comment_color);
  1796. class_desc->add_text(" setter");
  1797. class_desc->pop(); // color
  1798. _pop_code_font();
  1799. class_desc->pop(); // cell
  1800. method_line[prop.setter] = property_line[prop.name];
  1801. }
  1802. if (!prop.getter.is_empty()) {
  1803. class_desc->push_cell();
  1804. class_desc->pop(); // cell
  1805. class_desc->push_cell();
  1806. _push_code_font();
  1807. class_desc->push_color(theme_cache.text_color);
  1808. if (!method_map[prop.getter].arguments.is_empty()) {
  1809. // Getters with additional arguments are exposed in the method list, so we link them here for quick access.
  1810. class_desc->push_meta("@method " + prop.getter);
  1811. class_desc->add_text(prop.getter + "()");
  1812. class_desc->pop(); // meta
  1813. } else {
  1814. class_desc->add_text(prop.getter + "()");
  1815. }
  1816. class_desc->pop(); // color
  1817. class_desc->push_color(theme_cache.comment_color);
  1818. class_desc->add_text(" getter");
  1819. class_desc->pop(); // color
  1820. _pop_code_font();
  1821. class_desc->pop(); // cell
  1822. method_line[prop.getter] = property_line[prop.name];
  1823. }
  1824. }
  1825. class_desc->pop(); // table
  1826. class_desc->add_newline();
  1827. class_desc->add_newline();
  1828. class_desc->push_indent(1);
  1829. _push_normal_font();
  1830. class_desc->push_color(theme_cache.text_color);
  1831. bool has_prev_text = false;
  1832. if (prop.is_deprecated) {
  1833. has_prev_text = true;
  1834. DEPRECATED_DOC_MSG(HANDLE_DOC(prop.deprecated_message), TTR("This property may be changed or removed in future versions."));
  1835. }
  1836. if (prop.is_experimental) {
  1837. if (has_prev_text) {
  1838. class_desc->add_newline();
  1839. class_desc->add_newline();
  1840. }
  1841. has_prev_text = true;
  1842. EXPERIMENTAL_DOC_MSG(HANDLE_DOC(prop.experimental_message), TTR("This property may be changed or removed in future versions."));
  1843. }
  1844. const String descr = HANDLE_DOC(prop.description);
  1845. if (!descr.is_empty()) {
  1846. if (has_prev_text) {
  1847. class_desc->add_newline();
  1848. class_desc->add_newline();
  1849. }
  1850. has_prev_text = true;
  1851. _add_text(descr);
  1852. } else if (!has_prev_text) {
  1853. class_desc->add_image(get_editor_theme_icon(SNAME("Error")));
  1854. class_desc->add_text(" ");
  1855. class_desc->push_color(theme_cache.comment_color);
  1856. if (cd.is_script_doc) {
  1857. class_desc->add_text(TTR("There is currently no description for this property."));
  1858. } else {
  1859. class_desc->append_text(TTR("There is currently no description for this property. Please help us by [color=$color][url=$url]contributing one[/url][/color]!").replace("$url", CONTRIBUTE_URL).replace("$color", link_color_text));
  1860. }
  1861. class_desc->pop(); // color
  1862. }
  1863. // Add copy note to built-in properties returning `Packed*Array`.
  1864. if (!cd.is_script_doc && packed_array_types.has(prop.type)) {
  1865. class_desc->add_newline();
  1866. class_desc->add_newline();
  1867. _add_text(vformat(TTR("[b]Note:[/b] The returned array is [i]copied[/i] and any changes to it will not update the original property value. See [%s] for more details."), prop.type));
  1868. }
  1869. class_desc->pop(); // color
  1870. _pop_normal_font();
  1871. class_desc->pop(); // indent
  1872. }
  1873. }
  1874. // Constructor descriptions
  1875. if (!cd.constructors.is_empty()) {
  1876. _update_method_descriptions(cd, METHOD_TYPE_CONSTRUCTOR, cd.constructors);
  1877. }
  1878. // Method descriptions
  1879. if (!methods.is_empty()) {
  1880. _update_method_descriptions(cd, METHOD_TYPE_METHOD, methods);
  1881. }
  1882. // Operator descriptions
  1883. if (!cd.operators.is_empty()) {
  1884. _update_method_descriptions(cd, METHOD_TYPE_OPERATOR, cd.operators);
  1885. }
  1886. // Allow the document to be scrolled slightly below the end.
  1887. class_desc->add_newline();
  1888. class_desc->add_newline();
  1889. // Free the scroll.
  1890. scroll_locked = false;
  1891. #undef HANDLE_DOC
  1892. }
  1893. void EditorHelp::_request_help(const String &p_string) {
  1894. Error err = _goto_desc(p_string);
  1895. if (err == OK) {
  1896. EditorNode::get_singleton()->get_editor_main_screen()->select(EditorMainScreen::EDITOR_SCRIPT);
  1897. }
  1898. }
  1899. void EditorHelp::_help_callback(const String &p_topic) {
  1900. String what = p_topic.get_slice(":", 0);
  1901. String clss = p_topic.get_slice(":", 1);
  1902. String name;
  1903. if (p_topic.get_slice_count(":") == 3) {
  1904. name = p_topic.get_slice(":", 2);
  1905. }
  1906. _request_help(clss); // First go to class.
  1907. int line = 0;
  1908. if (what == "class_desc") {
  1909. line = description_line;
  1910. } else if (what == "class_signal") {
  1911. if (signal_line.has(name)) {
  1912. line = signal_line[name];
  1913. }
  1914. } else if (what == "class_method" || what == "class_method_desc") {
  1915. if (method_line.has(name)) {
  1916. line = method_line[name];
  1917. }
  1918. } else if (what == "class_property") {
  1919. if (property_line.has(name)) {
  1920. line = property_line[name];
  1921. }
  1922. } else if (what == "class_enum") {
  1923. if (enum_line.has(name)) {
  1924. line = enum_line[name];
  1925. }
  1926. } else if (what == "class_theme_item") {
  1927. if (theme_property_line.has(name)) {
  1928. line = theme_property_line[name];
  1929. }
  1930. } else if (what == "class_constant") {
  1931. if (constant_line.has(name)) {
  1932. line = constant_line[name];
  1933. }
  1934. } else if (what == "class_annotation") {
  1935. if (annotation_line.has(name)) {
  1936. line = annotation_line[name];
  1937. }
  1938. } else if (what == "class_global") {
  1939. if (constant_line.has(name)) {
  1940. line = constant_line[name];
  1941. } else if (method_line.has(name)) {
  1942. line = method_line[name];
  1943. } else {
  1944. HashMap<String, HashMap<String, int>>::Iterator iter = enum_values_line.begin();
  1945. while (true) {
  1946. if (iter->value.has(name)) {
  1947. line = iter->value[name];
  1948. break;
  1949. } else if (iter == enum_values_line.last()) {
  1950. break;
  1951. } else {
  1952. ++iter;
  1953. }
  1954. }
  1955. }
  1956. }
  1957. if (class_desc->is_finished()) {
  1958. class_desc->scroll_to_paragraph(line);
  1959. } else {
  1960. scroll_to = line;
  1961. }
  1962. }
  1963. static void _add_text_to_rt(const String &p_bbcode, RichTextLabel *p_rt, const Control *p_owner_node, const String &p_class) {
  1964. const DocTools *doc = EditorHelp::get_doc_data();
  1965. bool is_native = false;
  1966. {
  1967. const HashMap<String, DocData::ClassDoc>::ConstIterator E = doc->class_list.find(p_class);
  1968. if (E && !E->value.is_script_doc) {
  1969. is_native = true;
  1970. }
  1971. }
  1972. const bool using_tab_indent = int(EDITOR_GET("text_editor/behavior/indent/type")) == 0;
  1973. const Ref<Font> doc_font = p_owner_node->get_theme_font(SNAME("doc"), EditorStringName(EditorFonts));
  1974. const Ref<Font> doc_bold_font = p_owner_node->get_theme_font(SNAME("doc_bold"), EditorStringName(EditorFonts));
  1975. const Ref<Font> doc_italic_font = p_owner_node->get_theme_font(SNAME("doc_italic"), EditorStringName(EditorFonts));
  1976. const Ref<Font> doc_code_font = p_owner_node->get_theme_font(SNAME("doc_source"), EditorStringName(EditorFonts));
  1977. const Ref<Font> doc_kbd_font = p_owner_node->get_theme_font(SNAME("doc_keyboard"), EditorStringName(EditorFonts));
  1978. const int doc_font_size = p_owner_node->get_theme_font_size(SNAME("doc_size"), EditorStringName(EditorFonts));
  1979. const int doc_code_font_size = p_owner_node->get_theme_font_size(SNAME("doc_source_size"), EditorStringName(EditorFonts));
  1980. const int doc_kbd_font_size = p_owner_node->get_theme_font_size(SNAME("doc_keyboard_size"), EditorStringName(EditorFonts));
  1981. const Color type_color = p_owner_node->get_theme_color(SNAME("type_color"), SNAME("EditorHelp"));
  1982. const Color code_color = p_owner_node->get_theme_color(SNAME("code_color"), SNAME("EditorHelp"));
  1983. const Color kbd_color = p_owner_node->get_theme_color(SNAME("kbd_color"), SNAME("EditorHelp"));
  1984. const Color code_dark_color = Color(code_color, 0.8);
  1985. const Color link_color = p_owner_node->get_theme_color(SNAME("link_color"), SNAME("EditorHelp"));
  1986. const Color link_method_color = p_owner_node->get_theme_color(SNAME("accent_color"), EditorStringName(Editor));
  1987. const Color link_property_color = link_color.lerp(p_owner_node->get_theme_color(SNAME("accent_color"), EditorStringName(Editor)), 0.25);
  1988. const Color link_annotation_color = link_color.lerp(p_owner_node->get_theme_color(SNAME("accent_color"), EditorStringName(Editor)), 0.5);
  1989. const Color code_bg_color = p_owner_node->get_theme_color(SNAME("code_bg_color"), SNAME("EditorHelp"));
  1990. const Color kbd_bg_color = p_owner_node->get_theme_color(SNAME("kbd_bg_color"), SNAME("EditorHelp"));
  1991. const Color param_bg_color = p_owner_node->get_theme_color(SNAME("param_bg_color"), SNAME("EditorHelp"));
  1992. String bbcode = p_bbcode.dedent().replace("\t", "").replace("\r", "").strip_edges();
  1993. // Select the correct code examples.
  1994. switch ((int)EDITOR_GET("text_editor/help/class_reference_examples")) {
  1995. case 0: // GDScript
  1996. bbcode = bbcode.replace("[gdscript", "[codeblock lang=gdscript"); // Tag can have extra arguments.
  1997. bbcode = bbcode.replace("[/gdscript]", "[/codeblock]");
  1998. for (int pos = bbcode.find("[csharp"); pos != -1; pos = bbcode.find("[csharp")) {
  1999. int end_pos = bbcode.find("[/csharp]");
  2000. if (end_pos == -1) {
  2001. WARN_PRINT("Unclosed [csharp] block or parse fail in code (search for tag errors)");
  2002. break;
  2003. }
  2004. bbcode = bbcode.left(pos) + bbcode.substr(end_pos + 9); // 9 is length of "[/csharp]".
  2005. while (bbcode[pos] == '\n') {
  2006. bbcode = bbcode.left(pos) + bbcode.substr(pos + 1);
  2007. }
  2008. }
  2009. break;
  2010. case 1: // C#
  2011. bbcode = bbcode.replace("[csharp", "[codeblock lang=csharp"); // Tag can have extra arguments.
  2012. bbcode = bbcode.replace("[/csharp]", "[/codeblock]");
  2013. for (int pos = bbcode.find("[gdscript"); pos != -1; pos = bbcode.find("[gdscript")) {
  2014. int end_pos = bbcode.find("[/gdscript]");
  2015. if (end_pos == -1) {
  2016. WARN_PRINT("Unclosed [gdscript] block or parse fail in code (search for tag errors)");
  2017. break;
  2018. }
  2019. bbcode = bbcode.left(pos) + bbcode.substr(end_pos + 11); // 11 is length of "[/gdscript]".
  2020. while (bbcode[pos] == '\n') {
  2021. bbcode = bbcode.left(pos) + bbcode.substr(pos + 1);
  2022. }
  2023. }
  2024. break;
  2025. case 2: // GDScript and C#
  2026. bbcode = bbcode.replace("[csharp", "[b]C#:[/b]\n[codeblock lang=csharp"); // Tag can have extra arguments.
  2027. bbcode = bbcode.replace("[gdscript", "[b]GDScript:[/b]\n[codeblock lang=gdscript"); // Tag can have extra arguments.
  2028. bbcode = bbcode.replace("[/csharp]", "[/codeblock]");
  2029. bbcode = bbcode.replace("[/gdscript]", "[/codeblock]");
  2030. break;
  2031. }
  2032. // Remove codeblocks (they would be printed otherwise).
  2033. bbcode = bbcode.replace("[codeblocks]\n", "");
  2034. bbcode = bbcode.replace("\n[/codeblocks]", "");
  2035. bbcode = bbcode.replace("[codeblocks]", "");
  2036. bbcode = bbcode.replace("[/codeblocks]", "");
  2037. // Remove `\n` here because `\n` is replaced by `\n\n` later.
  2038. // Will be compensated when parsing `[/codeblock]`.
  2039. bbcode = bbcode.replace("[/codeblock]\n", "[/codeblock]");
  2040. List<String> tag_stack;
  2041. int pos = 0;
  2042. while (pos < bbcode.length()) {
  2043. int brk_pos = bbcode.find_char('[', pos);
  2044. if (brk_pos < 0) {
  2045. brk_pos = bbcode.length();
  2046. }
  2047. if (brk_pos > pos) {
  2048. p_rt->add_text(bbcode.substr(pos, brk_pos - pos).replace("\n", "\n\n"));
  2049. }
  2050. if (brk_pos == bbcode.length()) {
  2051. break; // Nothing else to add.
  2052. }
  2053. int brk_end = bbcode.find_char(']', brk_pos + 1);
  2054. if (brk_end == -1) {
  2055. p_rt->add_text(bbcode.substr(brk_pos, bbcode.length() - brk_pos).replace("\n", "\n\n"));
  2056. break;
  2057. }
  2058. const String tag = bbcode.substr(brk_pos + 1, brk_end - brk_pos - 1);
  2059. if (tag.begins_with("/")) {
  2060. bool tag_ok = tag_stack.size() && tag_stack.front()->get() == tag.substr(1);
  2061. if (!tag_ok) {
  2062. p_rt->add_text("[");
  2063. pos = brk_pos + 1;
  2064. continue;
  2065. }
  2066. tag_stack.pop_front();
  2067. pos = brk_end + 1;
  2068. if (tag == "/img") {
  2069. // Nothing to do.
  2070. } else if (tag == "/url") {
  2071. p_rt->pop(); // meta
  2072. p_rt->pop(); // color
  2073. p_rt->add_text(" ");
  2074. p_rt->add_image(p_owner_node->get_editor_theme_icon(SNAME("ExternalLink")), 0, doc_font_size, link_color);
  2075. } else {
  2076. p_rt->pop();
  2077. }
  2078. } else if (tag.begins_with("method ") || tag.begins_with("constructor ") || tag.begins_with("operator ") || tag.begins_with("member ") || tag.begins_with("signal ") || tag.begins_with("enum ") || tag.begins_with("constant ") || tag.begins_with("annotation ") || tag.begins_with("theme_item ")) {
  2079. const int tag_end = tag.find_char(' ');
  2080. const String link_tag = tag.left(tag_end);
  2081. const String link_target = tag.substr(tag_end + 1).lstrip(" ");
  2082. Color target_color = link_color;
  2083. RichTextLabel::MetaUnderline underline_mode = RichTextLabel::META_UNDERLINE_ON_HOVER;
  2084. if (link_tag == "method" || link_tag == "constructor" || link_tag == "operator") {
  2085. target_color = link_method_color;
  2086. } else if (link_tag == "member" || link_tag == "signal" || link_tag == "theme_item") {
  2087. target_color = link_property_color;
  2088. } else if (link_tag == "annotation") {
  2089. target_color = link_annotation_color;
  2090. } else {
  2091. // Better visibility for constants, enums, etc.
  2092. underline_mode = RichTextLabel::META_UNDERLINE_ALWAYS;
  2093. }
  2094. // Use monospace font to make clickable references
  2095. // easier to distinguish from inline code and other text.
  2096. p_rt->push_font(doc_code_font);
  2097. p_rt->push_font_size(doc_code_font_size);
  2098. p_rt->push_color(target_color);
  2099. p_rt->push_meta("@" + link_tag + " " + link_target, underline_mode);
  2100. if (link_tag == "member" &&
  2101. ((!link_target.contains_char('.') && (p_class == "ProjectSettings" || p_class == "EditorSettings")) ||
  2102. link_target.begins_with("ProjectSettings.") || link_target.begins_with("EditorSettings."))) {
  2103. // Special formatting for both ProjectSettings and EditorSettings.
  2104. String prefix;
  2105. if (link_target.begins_with("EditorSettings.")) {
  2106. prefix = "(" + TTR("Editor") + ") ";
  2107. }
  2108. const String setting_name = link_target.trim_prefix("ProjectSettings.").trim_prefix("EditorSettings.");
  2109. PackedStringArray setting_sections;
  2110. for (const String &section : setting_name.split("/", false)) {
  2111. setting_sections.append(EditorPropertyNameProcessor::get_singleton()->process_name(section, EditorPropertyNameProcessor::get_settings_style()));
  2112. }
  2113. p_rt->push_bold();
  2114. p_rt->add_text(prefix + String(" > ").join(setting_sections));
  2115. p_rt->pop(); // bold
  2116. } else {
  2117. p_rt->add_text(link_target + (link_tag == "method" ? "()" : ""));
  2118. }
  2119. p_rt->pop(); // meta
  2120. p_rt->pop(); // color
  2121. p_rt->pop(); // font_size
  2122. p_rt->pop(); // font
  2123. pos = brk_end + 1;
  2124. } else if (tag.begins_with("param ")) {
  2125. const int tag_end = tag.find_char(' ');
  2126. const String param_name = tag.substr(tag_end + 1).lstrip(" ");
  2127. // Use monospace font with translucent background color to make code easier to distinguish from other text.
  2128. p_rt->push_font(doc_code_font);
  2129. p_rt->push_font_size(doc_code_font_size);
  2130. p_rt->push_bgcolor(param_bg_color);
  2131. p_rt->push_color(code_color);
  2132. p_rt->add_text(param_name);
  2133. p_rt->pop(); // color
  2134. p_rt->pop(); // bgcolor
  2135. p_rt->pop(); // font_size
  2136. p_rt->pop(); // font
  2137. pos = brk_end + 1;
  2138. } else if (tag == p_class) {
  2139. // Use a bold font when class reference tags are in their own page.
  2140. p_rt->push_font(doc_bold_font);
  2141. p_rt->add_text(tag);
  2142. p_rt->pop(); // font
  2143. pos = brk_end + 1;
  2144. } else if (doc->class_list.has(tag)) {
  2145. // Use a monospace font for class reference tags such as [Node2D] or [SceneTree].
  2146. p_rt->push_font(doc_code_font);
  2147. p_rt->push_font_size(doc_code_font_size);
  2148. p_rt->push_color(type_color);
  2149. p_rt->push_meta("#" + tag, RichTextLabel::META_UNDERLINE_ON_HOVER);
  2150. p_rt->add_text(tag);
  2151. p_rt->pop(); // meta
  2152. p_rt->pop(); // color
  2153. p_rt->pop(); // font_size
  2154. p_rt->pop(); // font
  2155. pos = brk_end + 1;
  2156. } else if (tag == "b") {
  2157. // Use bold font.
  2158. p_rt->push_font(doc_bold_font);
  2159. pos = brk_end + 1;
  2160. tag_stack.push_front(tag);
  2161. } else if (tag == "i") {
  2162. // Use italics font.
  2163. p_rt->push_font(doc_italic_font);
  2164. pos = brk_end + 1;
  2165. tag_stack.push_front(tag);
  2166. } else if (tag == "code" || tag.begins_with("code ")) {
  2167. int end_pos = bbcode.find("[/code]", brk_end + 1);
  2168. if (end_pos < 0) {
  2169. end_pos = bbcode.length();
  2170. }
  2171. // Use monospace font with darkened background color to make code easier to distinguish from other text.
  2172. p_rt->push_font(doc_code_font);
  2173. p_rt->push_font_size(doc_code_font_size);
  2174. p_rt->push_bgcolor(code_bg_color);
  2175. p_rt->push_color(code_color.lerp(p_owner_node->get_theme_color(SNAME("error_color"), EditorStringName(Editor)), 0.6));
  2176. p_rt->add_text(bbcode.substr(brk_end + 1, end_pos - (brk_end + 1)));
  2177. p_rt->pop(); // color
  2178. p_rt->pop(); // bgcolor
  2179. p_rt->pop(); // font_size
  2180. p_rt->pop(); // font
  2181. pos = end_pos + 7; // `len("[/code]")`.
  2182. } else if (tag == "codeblock" || tag.begins_with("codeblock ")) {
  2183. int end_pos = bbcode.find("[/codeblock]", brk_end + 1);
  2184. if (end_pos < 0) {
  2185. end_pos = bbcode.length();
  2186. }
  2187. const String codeblock_text = bbcode.substr(brk_end + 1, end_pos - (brk_end + 1)).strip_edges();
  2188. String codeblock_copy_text = codeblock_text;
  2189. if (using_tab_indent) {
  2190. // Replace the code block's space indentation with tabs.
  2191. StringBuilder builder;
  2192. PackedStringArray text_lines = codeblock_copy_text.split("\n");
  2193. for (const String &line : text_lines) {
  2194. const String stripped_line = line.dedent();
  2195. const int space_count = line.length() - stripped_line.length();
  2196. if (builder.num_strings_appended() > 0) {
  2197. builder.append("\n");
  2198. }
  2199. if (space_count > 0) {
  2200. builder.append(String("\t").repeat(MAX(space_count / 4, 1)) + stripped_line);
  2201. } else {
  2202. builder.append(line);
  2203. }
  2204. }
  2205. codeblock_copy_text = builder.as_string();
  2206. }
  2207. String lang;
  2208. const PackedStringArray args = tag.trim_prefix("codeblock").split(" ", false);
  2209. for (int i = args.size() - 1; i >= 0; i--) {
  2210. if (args[i].begins_with("lang=")) {
  2211. lang = args[i].trim_prefix("lang=");
  2212. break;
  2213. }
  2214. }
  2215. // Use monospace font with darkened background color to make code easier to distinguish from other text.
  2216. // Use a single-column table with cell row background color instead of `[bgcolor]`.
  2217. // This makes the background color highlight cover the entire block, rather than individual lines.
  2218. p_rt->push_font(doc_code_font);
  2219. p_rt->push_font_size(doc_code_font_size);
  2220. p_rt->push_table(2);
  2221. p_rt->push_cell();
  2222. p_rt->set_cell_row_background_color(code_bg_color, Color(code_bg_color, 0.99));
  2223. p_rt->set_cell_padding(Rect2(10 * EDSCALE, 10 * EDSCALE, 10 * EDSCALE, 10 * EDSCALE));
  2224. p_rt->push_color(code_dark_color);
  2225. bool codeblock_printed = false;
  2226. #ifdef MODULE_GDSCRIPT_ENABLED
  2227. if (!codeblock_printed && (lang.is_empty() || lang == "gdscript")) {
  2228. EditorHelpHighlighter::get_singleton()->highlight(p_rt, EditorHelpHighlighter::LANGUAGE_GDSCRIPT, codeblock_text, is_native);
  2229. codeblock_printed = true;
  2230. }
  2231. #endif
  2232. #ifdef MODULE_MONO_ENABLED
  2233. if (!codeblock_printed && lang == "csharp") {
  2234. EditorHelpHighlighter::get_singleton()->highlight(p_rt, EditorHelpHighlighter::LANGUAGE_CSHARP, codeblock_text, is_native);
  2235. codeblock_printed = true;
  2236. }
  2237. #endif
  2238. if (!codeblock_printed) {
  2239. p_rt->add_text(codeblock_text);
  2240. codeblock_printed = true;
  2241. }
  2242. p_rt->pop(); // color
  2243. p_rt->pop(); // cell
  2244. // Copy codeblock button.
  2245. p_rt->push_cell();
  2246. p_rt->set_cell_row_background_color(code_bg_color, Color(code_bg_color, 0.99));
  2247. p_rt->set_cell_padding(Rect2(0, 10 * EDSCALE, 0, 10 * EDSCALE));
  2248. p_rt->set_cell_size_override(Vector2(1, 1), Vector2(10, 10) * EDSCALE);
  2249. p_rt->push_meta("^" + codeblock_copy_text, RichTextLabel::META_UNDERLINE_ON_HOVER);
  2250. p_rt->add_image(p_owner_node->get_editor_theme_icon(SNAME("ActionCopy")), 24 * EDSCALE, 24 * EDSCALE, Color(link_property_color, 0.3), INLINE_ALIGNMENT_BOTTOM_TO, Rect2(), Variant(), false, TTR("Click to copy."));
  2251. p_rt->pop(); // meta
  2252. p_rt->pop(); // cell
  2253. p_rt->pop(); // table
  2254. p_rt->pop(); // font_size
  2255. p_rt->pop(); // font
  2256. pos = end_pos + 12; // `len("[/codeblock]")`.
  2257. // Compensate for `\n` removed before the loop.
  2258. if (pos < bbcode.length()) {
  2259. p_rt->add_newline();
  2260. }
  2261. } else if (tag == "kbd") {
  2262. int end_pos = bbcode.find("[/kbd]", brk_end + 1);
  2263. if (end_pos < 0) {
  2264. end_pos = bbcode.length();
  2265. }
  2266. // Use keyboard font with custom color and background color.
  2267. p_rt->push_font(doc_kbd_font);
  2268. p_rt->push_font_size(doc_kbd_font_size);
  2269. p_rt->push_bgcolor(kbd_bg_color);
  2270. p_rt->push_color(kbd_color);
  2271. p_rt->add_text(bbcode.substr(brk_end + 1, end_pos - (brk_end + 1)));
  2272. p_rt->pop(); // color
  2273. p_rt->pop(); // bgcolor
  2274. p_rt->pop(); // font_size
  2275. p_rt->pop(); // font
  2276. pos = end_pos + 6; // `len("[/kbd]")`.
  2277. } else if (tag == "center") {
  2278. // Align to center.
  2279. p_rt->push_paragraph(HORIZONTAL_ALIGNMENT_CENTER, Control::TEXT_DIRECTION_AUTO, "");
  2280. pos = brk_end + 1;
  2281. tag_stack.push_front(tag);
  2282. } else if (tag == "br") {
  2283. // Force a line break.
  2284. p_rt->add_newline();
  2285. pos = brk_end + 1;
  2286. } else if (tag == "u") {
  2287. // Use underline.
  2288. p_rt->push_underline();
  2289. pos = brk_end + 1;
  2290. tag_stack.push_front(tag);
  2291. } else if (tag == "s") {
  2292. // Use strikethrough.
  2293. p_rt->push_strikethrough();
  2294. pos = brk_end + 1;
  2295. tag_stack.push_front(tag);
  2296. } else if (tag == "lb") {
  2297. p_rt->add_text("[");
  2298. pos = brk_end + 1;
  2299. } else if (tag == "rb") {
  2300. p_rt->add_text("]");
  2301. pos = brk_end + 1;
  2302. } else if (tag == "url" || tag.begins_with("url=")) {
  2303. String url;
  2304. if (tag.begins_with("url=")) {
  2305. url = tag.substr(4);
  2306. } else {
  2307. int end = bbcode.find_char('[', brk_end);
  2308. if (end == -1) {
  2309. end = bbcode.length();
  2310. }
  2311. url = bbcode.substr(brk_end + 1, end - brk_end - 1);
  2312. }
  2313. p_rt->push_color(link_color);
  2314. p_rt->push_meta(url, RichTextLabel::META_UNDERLINE_ON_HOVER, url + "\n\n" + TTR("Click to open in browser."));
  2315. pos = brk_end + 1;
  2316. tag_stack.push_front("url");
  2317. } else if (tag.begins_with("img")) {
  2318. int width = 0;
  2319. int height = 0;
  2320. bool size_in_percent = false;
  2321. if (tag.length() > 4) {
  2322. Vector<String> subtags = tag.substr(4).split(" ");
  2323. HashMap<String, String> bbcode_options;
  2324. for (int i = 0; i < subtags.size(); i++) {
  2325. const String &expr = subtags[i];
  2326. int value_pos = expr.find_char('=');
  2327. if (value_pos > -1) {
  2328. bbcode_options[expr.left(value_pos)] = expr.substr(value_pos + 1).unquote();
  2329. }
  2330. }
  2331. HashMap<String, String>::Iterator width_option = bbcode_options.find("width");
  2332. if (width_option) {
  2333. width = width_option->value.to_int();
  2334. if (width_option->value.ends_with("%")) {
  2335. size_in_percent = true;
  2336. }
  2337. }
  2338. HashMap<String, String>::Iterator height_option = bbcode_options.find("height");
  2339. if (height_option) {
  2340. height = height_option->value.to_int();
  2341. if (height_option->value.ends_with("%")) {
  2342. size_in_percent = true;
  2343. }
  2344. }
  2345. }
  2346. int end = bbcode.find_char('[', brk_end);
  2347. if (end == -1) {
  2348. end = bbcode.length();
  2349. }
  2350. String image_path = bbcode.substr(brk_end + 1, end - brk_end - 1);
  2351. p_rt->add_image(ResourceLoader::load(image_path, "Texture2D"), width, height, Color(1, 1, 1), INLINE_ALIGNMENT_CENTER, Rect2(), Variant(), false, String(), size_in_percent);
  2352. pos = end;
  2353. tag_stack.push_front("img");
  2354. } else if (tag.begins_with("color=")) {
  2355. String col = tag.substr(6);
  2356. Color color = Color::from_string(col, Color());
  2357. p_rt->push_color(color);
  2358. pos = brk_end + 1;
  2359. tag_stack.push_front("color");
  2360. } else if (tag.begins_with("font=")) {
  2361. String font_path = tag.substr(5);
  2362. Ref<Font> font = ResourceLoader::load(font_path, "Font");
  2363. if (font.is_valid()) {
  2364. p_rt->push_font(font);
  2365. } else {
  2366. p_rt->push_font(doc_font);
  2367. }
  2368. pos = brk_end + 1;
  2369. tag_stack.push_front("font");
  2370. } else {
  2371. p_rt->add_text("["); // Ignore.
  2372. pos = brk_pos + 1;
  2373. }
  2374. }
  2375. // Close unclosed tags.
  2376. for (const String &tag : tag_stack) {
  2377. if (tag != "img") {
  2378. p_rt->pop();
  2379. }
  2380. }
  2381. }
  2382. void EditorHelp::_add_text(const String &p_bbcode) {
  2383. _add_text_to_rt(p_bbcode, class_desc, this, edited_class);
  2384. }
  2385. int EditorHelp::doc_generation_count = 0;
  2386. String EditorHelp::doc_version_hash;
  2387. Thread EditorHelp::worker_thread;
  2388. void EditorHelp::_wait_for_thread() {
  2389. if (worker_thread.is_started()) {
  2390. worker_thread.wait_to_finish();
  2391. }
  2392. }
  2393. void EditorHelp::_compute_doc_version_hash() {
  2394. uint32_t version_hash = Engine::get_singleton()->get_version_info().hash();
  2395. doc_version_hash = vformat("%d/%d/%d/%s", version_hash, ClassDB::get_api_hash(ClassDB::API_CORE), ClassDB::get_api_hash(ClassDB::API_EDITOR), _doc_data_hash);
  2396. }
  2397. String EditorHelp::get_cache_full_path() {
  2398. return EditorPaths::get_singleton()->get_cache_dir().path_join(vformat("editor_doc_cache-%d.%d.res", VERSION_MAJOR, VERSION_MINOR));
  2399. }
  2400. void EditorHelp::load_xml_buffer(const uint8_t *p_buffer, int p_size) {
  2401. if (!ext_doc) {
  2402. ext_doc = memnew(DocTools);
  2403. }
  2404. ext_doc->load_xml(p_buffer, p_size);
  2405. if (doc) {
  2406. doc->load_xml(p_buffer, p_size);
  2407. }
  2408. }
  2409. void EditorHelp::remove_class(const String &p_class) {
  2410. if (ext_doc && ext_doc->has_doc(p_class)) {
  2411. ext_doc->remove_doc(p_class);
  2412. }
  2413. if (doc && doc->has_doc(p_class)) {
  2414. doc->remove_doc(p_class);
  2415. }
  2416. }
  2417. void EditorHelp::_load_doc_thread(void *p_udata) {
  2418. Ref<Resource> cache_res = ResourceLoader::load(get_cache_full_path());
  2419. if (cache_res.is_valid() && cache_res->get_meta("version_hash", "") == doc_version_hash) {
  2420. Array classes = cache_res->get_meta("classes", Array());
  2421. for (int i = 0; i < classes.size(); i++) {
  2422. doc->add_doc(DocData::ClassDoc::from_dict(classes[i]));
  2423. }
  2424. // Extensions' docs are not cached. Generate them now (on the main thread).
  2425. callable_mp_static(&EditorHelp::_gen_extensions_docs).call_deferred();
  2426. } else {
  2427. // We have to go back to the main thread to start from scratch, bypassing any possibly existing cache.
  2428. callable_mp_static(&EditorHelp::generate_doc).call_deferred(false);
  2429. }
  2430. OS::get_singleton()->benchmark_end_measure("EditorHelp", vformat("Generate Documentation (Run %d)", doc_generation_count));
  2431. }
  2432. void EditorHelp::_gen_doc_thread(void *p_udata) {
  2433. DocTools compdoc;
  2434. compdoc.load_compressed(_doc_data_compressed, _doc_data_compressed_size, _doc_data_uncompressed_size);
  2435. doc->merge_from(compdoc); // Ensure all is up to date.
  2436. Ref<Resource> cache_res;
  2437. cache_res.instantiate();
  2438. cache_res->set_meta("version_hash", doc_version_hash);
  2439. Array classes;
  2440. for (const KeyValue<String, DocData::ClassDoc> &E : doc->class_list) {
  2441. if (ClassDB::class_exists(E.value.name)) {
  2442. ClassDB::APIType api = ClassDB::get_api_type(E.value.name);
  2443. if (api == ClassDB::API_EXTENSION || api == ClassDB::API_EDITOR_EXTENSION) {
  2444. continue;
  2445. }
  2446. }
  2447. classes.push_back(DocData::ClassDoc::to_dict(E.value));
  2448. }
  2449. cache_res->set_meta("classes", classes);
  2450. Error err = ResourceSaver::save(cache_res, get_cache_full_path(), ResourceSaver::FLAG_COMPRESS);
  2451. if (err) {
  2452. ERR_PRINT("Cannot save editor help cache (" + get_cache_full_path() + ").");
  2453. }
  2454. OS::get_singleton()->benchmark_end_measure("EditorHelp", vformat("Generate Documentation (Run %d)", doc_generation_count));
  2455. }
  2456. void EditorHelp::_gen_extensions_docs() {
  2457. doc->generate((DocTools::GENERATE_FLAG_SKIP_BASIC_TYPES | DocTools::GENERATE_FLAG_EXTENSION_CLASSES_ONLY));
  2458. // Append extra doc data, as it gets overridden by the generation step.
  2459. if (ext_doc) {
  2460. doc->merge_from(*ext_doc);
  2461. }
  2462. }
  2463. void EditorHelp::generate_doc(bool p_use_cache) {
  2464. doc_generation_count++;
  2465. OS::get_singleton()->benchmark_begin_measure("EditorHelp", vformat("Generate Documentation (Run %d)", doc_generation_count));
  2466. // In case not the first attempt.
  2467. _wait_for_thread();
  2468. if (!doc) {
  2469. doc = memnew(DocTools);
  2470. }
  2471. if (doc_version_hash.is_empty()) {
  2472. _compute_doc_version_hash();
  2473. }
  2474. if (p_use_cache && FileAccess::exists(get_cache_full_path())) {
  2475. worker_thread.start(_load_doc_thread, nullptr);
  2476. } else {
  2477. print_verbose("Regenerating editor help cache");
  2478. doc->generate();
  2479. worker_thread.start(_gen_doc_thread, nullptr);
  2480. }
  2481. }
  2482. void EditorHelp::_toggle_scripts_pressed() {
  2483. ScriptEditor::get_singleton()->toggle_scripts_panel();
  2484. update_toggle_scripts_button();
  2485. }
  2486. void EditorHelp::_notification(int p_what) {
  2487. switch (p_what) {
  2488. case NOTIFICATION_POSTINITIALIZE: {
  2489. // Requires theme to be up to date.
  2490. _class_desc_resized(false);
  2491. } break;
  2492. case EditorSettings::NOTIFICATION_EDITOR_SETTINGS_CHANGED: {
  2493. bool need_update = false;
  2494. if (EditorSettings::get_singleton()->check_changed_settings_in_group("text_editor/help")) {
  2495. need_update = true;
  2496. }
  2497. #if defined(MODULE_GDSCRIPT_ENABLED) || defined(MODULE_MONO_ENABLED)
  2498. if (!need_update && EditorSettings::get_singleton()->check_changed_settings_in_group("text_editor/theme/highlighting")) {
  2499. need_update = true;
  2500. }
  2501. #endif
  2502. if (!need_update) {
  2503. break;
  2504. }
  2505. [[fallthrough]];
  2506. }
  2507. case NOTIFICATION_READY: {
  2508. _wait_for_thread();
  2509. _update_doc();
  2510. } break;
  2511. case NOTIFICATION_THEME_CHANGED: {
  2512. if (is_inside_tree()) {
  2513. _class_desc_resized(true);
  2514. }
  2515. update_toggle_scripts_button();
  2516. } break;
  2517. case NOTIFICATION_VISIBILITY_CHANGED: {
  2518. update_toggle_scripts_button();
  2519. } break;
  2520. }
  2521. }
  2522. void EditorHelp::go_to_help(const String &p_help) {
  2523. _wait_for_thread();
  2524. _help_callback(p_help);
  2525. }
  2526. void EditorHelp::go_to_class(const String &p_class) {
  2527. _wait_for_thread();
  2528. _goto_desc(p_class);
  2529. }
  2530. void EditorHelp::update_doc() {
  2531. _wait_for_thread();
  2532. ERR_FAIL_COND(!doc->class_list.has(edited_class));
  2533. ERR_FAIL_COND(!doc->class_list[edited_class].is_script_doc);
  2534. _update_doc();
  2535. }
  2536. void EditorHelp::cleanup_doc() {
  2537. _wait_for_thread();
  2538. memdelete(doc);
  2539. doc = nullptr;
  2540. }
  2541. Vector<Pair<String, int>> EditorHelp::get_sections() {
  2542. _wait_for_thread();
  2543. Vector<Pair<String, int>> sections;
  2544. for (int i = 0; i < section_line.size(); i++) {
  2545. sections.push_back(Pair<String, int>(section_line[i].first, i));
  2546. }
  2547. return sections;
  2548. }
  2549. void EditorHelp::scroll_to_section(int p_section_index) {
  2550. _wait_for_thread();
  2551. int line = section_line[p_section_index].second;
  2552. if (class_desc->is_finished()) {
  2553. class_desc->scroll_to_paragraph(line);
  2554. } else {
  2555. scroll_to = line;
  2556. }
  2557. }
  2558. void EditorHelp::popup_search() {
  2559. _wait_for_thread();
  2560. find_bar->popup_search();
  2561. }
  2562. String EditorHelp::get_class() {
  2563. return edited_class;
  2564. }
  2565. void EditorHelp::search_again(bool p_search_previous) {
  2566. _search(p_search_previous);
  2567. }
  2568. int EditorHelp::get_scroll() const {
  2569. return class_desc->get_v_scroll_bar()->get_value();
  2570. }
  2571. void EditorHelp::set_scroll(int p_scroll) {
  2572. class_desc->get_v_scroll_bar()->set_value(p_scroll);
  2573. }
  2574. void EditorHelp::update_toggle_scripts_button() {
  2575. if (is_layout_rtl()) {
  2576. toggle_scripts_button->set_button_icon(get_editor_theme_icon(ScriptEditor::get_singleton()->is_scripts_panel_toggled() ? SNAME("Forward") : SNAME("Back")));
  2577. } else {
  2578. toggle_scripts_button->set_button_icon(get_editor_theme_icon(ScriptEditor::get_singleton()->is_scripts_panel_toggled() ? SNAME("Back") : SNAME("Forward")));
  2579. }
  2580. toggle_scripts_button->set_tooltip_text(vformat("%s (%s)", TTR("Toggle Scripts Panel"), ED_GET_SHORTCUT("script_editor/toggle_scripts_panel")->get_as_text()));
  2581. }
  2582. void EditorHelp::_bind_methods() {
  2583. ClassDB::bind_method("_class_list_select", &EditorHelp::_class_list_select);
  2584. ClassDB::bind_method("_request_help", &EditorHelp::_request_help);
  2585. ClassDB::bind_method("_search", &EditorHelp::_search);
  2586. ClassDB::bind_method("_help_callback", &EditorHelp::_help_callback);
  2587. ADD_SIGNAL(MethodInfo("go_to_help"));
  2588. ADD_SIGNAL(MethodInfo("request_save_history"));
  2589. }
  2590. void EditorHelp::init_gdext_pointers() {
  2591. GDExtensionEditorHelp::editor_help_load_xml_buffer = &EditorHelp::load_xml_buffer;
  2592. GDExtensionEditorHelp::editor_help_remove_class = &EditorHelp::remove_class;
  2593. }
  2594. EditorHelp::EditorHelp() {
  2595. set_custom_minimum_size(Size2(150 * EDSCALE, 0));
  2596. class_desc = memnew(RichTextLabel);
  2597. class_desc->set_tab_size(8);
  2598. add_child(class_desc);
  2599. class_desc->set_threaded(true);
  2600. class_desc->set_v_size_flags(SIZE_EXPAND_FILL);
  2601. class_desc->connect(SceneStringName(finished), callable_mp(this, &EditorHelp::_class_desc_finished));
  2602. class_desc->connect("meta_clicked", callable_mp(this, &EditorHelp::_class_desc_select));
  2603. class_desc->connect(SceneStringName(gui_input), callable_mp(this, &EditorHelp::_class_desc_input));
  2604. class_desc->connect(SceneStringName(resized), callable_mp(this, &EditorHelp::_class_desc_resized).bind(false));
  2605. // Added second so it opens at the bottom so it won't offset the entire widget.
  2606. find_bar = memnew(FindBar);
  2607. add_child(find_bar);
  2608. find_bar->hide();
  2609. find_bar->set_rich_text_label(class_desc);
  2610. status_bar = memnew(HBoxContainer);
  2611. add_child(status_bar);
  2612. status_bar->set_h_size_flags(SIZE_EXPAND_FILL);
  2613. status_bar->set_custom_minimum_size(Size2(0, 24 * EDSCALE));
  2614. toggle_scripts_button = memnew(Button);
  2615. toggle_scripts_button->set_flat(true);
  2616. toggle_scripts_button->connect(SceneStringName(pressed), callable_mp(this, &EditorHelp::_toggle_scripts_pressed));
  2617. status_bar->add_child(toggle_scripts_button);
  2618. class_desc->set_selection_enabled(true);
  2619. class_desc->set_context_menu_enabled(true);
  2620. class_desc->hide();
  2621. }
  2622. EditorHelp::~EditorHelp() {
  2623. }
  2624. DocTools *EditorHelp::get_doc_data() {
  2625. _wait_for_thread();
  2626. return doc;
  2627. }
  2628. /// EditorHelpBit ///
  2629. #define HANDLE_DOC(m_string) ((is_native ? DTR(m_string) : (m_string)).strip_edges())
  2630. EditorHelpBit::HelpData EditorHelpBit::_get_class_help_data(const StringName &p_class_name) {
  2631. if (doc_class_cache.has(p_class_name)) {
  2632. return doc_class_cache[p_class_name];
  2633. }
  2634. HelpData result;
  2635. const HashMap<String, DocData::ClassDoc>::ConstIterator E = EditorHelp::get_doc_data()->class_list.find(p_class_name);
  2636. if (E) {
  2637. // Non-native class shouldn't be cached, nor translated.
  2638. const bool is_native = !E->value.is_script_doc;
  2639. result.description = HANDLE_DOC(E->value.brief_description);
  2640. if (E->value.is_deprecated) {
  2641. if (E->value.deprecated_message.is_empty()) {
  2642. result.deprecated_message = TTR("This class may be changed or removed in future versions.");
  2643. } else {
  2644. result.deprecated_message = HANDLE_DOC(E->value.deprecated_message);
  2645. }
  2646. }
  2647. if (E->value.is_experimental) {
  2648. if (E->value.experimental_message.is_empty()) {
  2649. result.experimental_message = TTR("This class may be changed or removed in future versions.");
  2650. } else {
  2651. result.experimental_message = HANDLE_DOC(E->value.experimental_message);
  2652. }
  2653. }
  2654. if (is_native) {
  2655. doc_class_cache[p_class_name] = result;
  2656. }
  2657. }
  2658. return result;
  2659. }
  2660. EditorHelpBit::HelpData EditorHelpBit::_get_property_help_data(const StringName &p_class_name, const StringName &p_property_name) {
  2661. if (doc_property_cache.has(p_class_name) && doc_property_cache[p_class_name].has(p_property_name)) {
  2662. return doc_property_cache[p_class_name][p_property_name];
  2663. }
  2664. HelpData result;
  2665. const DocTools *dd = EditorHelp::get_doc_data();
  2666. const HashMap<String, DocData::ClassDoc>::ConstIterator E = dd->class_list.find(p_class_name);
  2667. if (E) {
  2668. // Non-native properties shouldn't be cached, nor translated.
  2669. const bool is_native = !E->value.is_script_doc;
  2670. for (const DocData::PropertyDoc &property : E->value.properties) {
  2671. HelpData current;
  2672. current.description = HANDLE_DOC(property.description);
  2673. if (property.is_deprecated) {
  2674. if (property.deprecated_message.is_empty()) {
  2675. current.deprecated_message = TTR("This property may be changed or removed in future versions.");
  2676. } else {
  2677. current.deprecated_message = HANDLE_DOC(property.deprecated_message);
  2678. }
  2679. }
  2680. if (property.is_experimental) {
  2681. if (property.experimental_message.is_empty()) {
  2682. current.experimental_message = TTR("This property may be changed or removed in future versions.");
  2683. } else {
  2684. current.experimental_message = HANDLE_DOC(property.experimental_message);
  2685. }
  2686. }
  2687. String enum_class_name;
  2688. String enum_name;
  2689. if (CoreConstants::is_global_enum(property.enumeration)) {
  2690. enum_class_name = "@GlobalScope";
  2691. enum_name = property.enumeration;
  2692. } else {
  2693. const int dot_pos = property.enumeration.rfind_char('.');
  2694. if (dot_pos >= 0) {
  2695. enum_class_name = property.enumeration.left(dot_pos);
  2696. enum_name = property.enumeration.substr(dot_pos + 1);
  2697. }
  2698. }
  2699. if (!enum_class_name.is_empty() && !enum_name.is_empty()) {
  2700. // Classes can use enums from other classes, so check from which it came.
  2701. const HashMap<String, DocData::ClassDoc>::ConstIterator enum_class = dd->class_list.find(enum_class_name);
  2702. if (enum_class) {
  2703. const String enum_prefix = EditorPropertyNameProcessor::get_singleton()->process_name(enum_name, EditorPropertyNameProcessor::STYLE_CAPITALIZED) + " ";
  2704. for (DocData::ConstantDoc constant : enum_class->value.constants) {
  2705. // Don't display `_MAX` enum value descriptions, as these are never exposed in the inspector.
  2706. if (constant.enumeration == enum_name && !constant.name.ends_with("_MAX")) {
  2707. // Prettify the enum value display, so that "<ENUM_NAME>_<ITEM>" becomes "Item".
  2708. const String item_name = EditorPropertyNameProcessor::get_singleton()->process_name(constant.name, EditorPropertyNameProcessor::STYLE_CAPITALIZED).trim_prefix(enum_prefix);
  2709. String item_descr = HANDLE_DOC(constant.description);
  2710. if (item_descr.is_empty()) {
  2711. item_descr = "[color=<EditorHelpBitCommentColor>][i]" + TTR("No description available.") + "[/i][/color]";
  2712. }
  2713. current.description += vformat("\n[b]%s:[/b] %s", item_name, item_descr);
  2714. }
  2715. }
  2716. current.description = current.description.lstrip("\n");
  2717. }
  2718. }
  2719. if (property.name == p_property_name) {
  2720. result = current;
  2721. if (!is_native) {
  2722. break;
  2723. }
  2724. }
  2725. if (is_native) {
  2726. doc_property_cache[p_class_name][property.name] = current;
  2727. }
  2728. }
  2729. }
  2730. return result;
  2731. }
  2732. EditorHelpBit::HelpData EditorHelpBit::_get_method_help_data(const StringName &p_class_name, const StringName &p_method_name) {
  2733. if (doc_method_cache.has(p_class_name) && doc_method_cache[p_class_name].has(p_method_name)) {
  2734. return doc_method_cache[p_class_name][p_method_name];
  2735. }
  2736. HelpData result;
  2737. const HashMap<String, DocData::ClassDoc>::ConstIterator E = EditorHelp::get_doc_data()->class_list.find(p_class_name);
  2738. if (E) {
  2739. // Non-native methods shouldn't be cached, nor translated.
  2740. const bool is_native = !E->value.is_script_doc;
  2741. for (const DocData::MethodDoc &method : E->value.methods) {
  2742. HelpData current;
  2743. current.description = HANDLE_DOC(method.description);
  2744. if (method.is_deprecated) {
  2745. if (method.deprecated_message.is_empty()) {
  2746. current.deprecated_message = TTR("This method may be changed or removed in future versions.");
  2747. } else {
  2748. current.deprecated_message = HANDLE_DOC(method.deprecated_message);
  2749. }
  2750. }
  2751. if (method.is_experimental) {
  2752. if (method.experimental_message.is_empty()) {
  2753. current.experimental_message = TTR("This method may be changed or removed in future versions.");
  2754. } else {
  2755. current.experimental_message = HANDLE_DOC(method.experimental_message);
  2756. }
  2757. }
  2758. current.doc_type = { method.return_type, method.return_enum, method.return_is_bitfield };
  2759. for (const DocData::ArgumentDoc &argument : method.arguments) {
  2760. const DocType argument_type = { argument.type, argument.enumeration, argument.is_bitfield };
  2761. current.arguments.push_back({ argument.name, argument_type, argument.default_value });
  2762. }
  2763. if (method.name == p_method_name) {
  2764. result = current;
  2765. if (!is_native) {
  2766. break;
  2767. }
  2768. }
  2769. if (is_native) {
  2770. doc_method_cache[p_class_name][method.name] = current;
  2771. }
  2772. }
  2773. }
  2774. return result;
  2775. }
  2776. EditorHelpBit::HelpData EditorHelpBit::_get_signal_help_data(const StringName &p_class_name, const StringName &p_signal_name) {
  2777. if (doc_signal_cache.has(p_class_name) && doc_signal_cache[p_class_name].has(p_signal_name)) {
  2778. return doc_signal_cache[p_class_name][p_signal_name];
  2779. }
  2780. HelpData result;
  2781. const HashMap<String, DocData::ClassDoc>::ConstIterator E = EditorHelp::get_doc_data()->class_list.find(p_class_name);
  2782. if (E) {
  2783. // Non-native signals shouldn't be cached, nor translated.
  2784. const bool is_native = !E->value.is_script_doc;
  2785. for (const DocData::MethodDoc &signal : E->value.signals) {
  2786. HelpData current;
  2787. current.description = HANDLE_DOC(signal.description);
  2788. if (signal.is_deprecated) {
  2789. if (signal.deprecated_message.is_empty()) {
  2790. current.deprecated_message = TTR("This signal may be changed or removed in future versions.");
  2791. } else {
  2792. current.deprecated_message = HANDLE_DOC(signal.deprecated_message);
  2793. }
  2794. }
  2795. if (signal.is_experimental) {
  2796. if (signal.experimental_message.is_empty()) {
  2797. current.experimental_message = TTR("This signal may be changed or removed in future versions.");
  2798. } else {
  2799. current.experimental_message = HANDLE_DOC(signal.experimental_message);
  2800. }
  2801. }
  2802. for (const DocData::ArgumentDoc &argument : signal.arguments) {
  2803. const DocType argument_type = { argument.type, argument.enumeration, argument.is_bitfield };
  2804. current.arguments.push_back({ argument.name, argument_type, argument.default_value });
  2805. }
  2806. if (signal.name == p_signal_name) {
  2807. result = current;
  2808. if (!is_native) {
  2809. break;
  2810. }
  2811. }
  2812. if (is_native) {
  2813. doc_signal_cache[p_class_name][signal.name] = current;
  2814. }
  2815. }
  2816. }
  2817. return result;
  2818. }
  2819. EditorHelpBit::HelpData EditorHelpBit::_get_theme_item_help_data(const StringName &p_class_name, const StringName &p_theme_item_name) {
  2820. if (doc_theme_item_cache.has(p_class_name) && doc_theme_item_cache[p_class_name].has(p_theme_item_name)) {
  2821. return doc_theme_item_cache[p_class_name][p_theme_item_name];
  2822. }
  2823. HelpData result;
  2824. bool found = false;
  2825. const DocTools *dd = EditorHelp::get_doc_data();
  2826. HashMap<String, DocData::ClassDoc>::ConstIterator E = dd->class_list.find(p_class_name);
  2827. while (E) {
  2828. // Non-native theme items shouldn't be cached, nor translated.
  2829. const bool is_native = !E->value.is_script_doc;
  2830. for (const DocData::ThemeItemDoc &theme_item : E->value.theme_properties) {
  2831. HelpData current;
  2832. current.description = HANDLE_DOC(theme_item.description);
  2833. if (theme_item.is_deprecated) {
  2834. if (theme_item.deprecated_message.is_empty()) {
  2835. current.deprecated_message = TTR("This theme property may be changed or removed in future versions.");
  2836. } else {
  2837. current.deprecated_message = HANDLE_DOC(theme_item.deprecated_message);
  2838. }
  2839. }
  2840. if (theme_item.is_experimental) {
  2841. if (theme_item.experimental_message.is_empty()) {
  2842. current.experimental_message = TTR("This theme property may be changed or removed in future versions.");
  2843. } else {
  2844. current.experimental_message = HANDLE_DOC(theme_item.experimental_message);
  2845. }
  2846. }
  2847. if (theme_item.name == p_theme_item_name) {
  2848. result = current;
  2849. found = true;
  2850. if (!is_native) {
  2851. break;
  2852. }
  2853. }
  2854. if (is_native) {
  2855. doc_theme_item_cache[p_class_name][theme_item.name] = current;
  2856. }
  2857. }
  2858. if (found || E->value.inherits.is_empty()) {
  2859. break;
  2860. }
  2861. // Check for inherited theme items.
  2862. E = dd->class_list.find(E->value.inherits);
  2863. }
  2864. return result;
  2865. }
  2866. #undef HANDLE_DOC
  2867. void EditorHelpBit::_add_type_to_title(const DocType &p_doc_type) {
  2868. _add_type_to_rt(p_doc_type.type, p_doc_type.enumeration, p_doc_type.is_bitfield, title, this, symbol_class_name);
  2869. }
  2870. void EditorHelpBit::_update_labels() {
  2871. const Ref<Font> doc_bold_font = get_theme_font(SNAME("doc_bold"), EditorStringName(EditorFonts));
  2872. if (!symbol_visible_type.is_empty() || !symbol_name.is_empty()) {
  2873. title->clear();
  2874. title->push_font(doc_bold_font);
  2875. if (!symbol_visible_type.is_empty()) {
  2876. title->push_color(get_theme_color(SNAME("title_color"), SNAME("EditorHelp")));
  2877. title->add_text(symbol_visible_type);
  2878. title->pop(); // color
  2879. }
  2880. if (!symbol_visible_type.is_empty() && !symbol_name.is_empty()) {
  2881. title->add_text(" ");
  2882. }
  2883. if (!symbol_name.is_empty()) {
  2884. title->push_underline();
  2885. title->add_text(symbol_name);
  2886. title->pop(); // underline
  2887. }
  2888. title->pop(); // font
  2889. if (symbol_type == "method" || symbol_type == "signal") {
  2890. const Color symbol_color = get_theme_color(SNAME("symbol_color"), SNAME("EditorHelp"));
  2891. const Color value_color = get_theme_color(SNAME("value_color"), SNAME("EditorHelp"));
  2892. title->push_font(get_theme_font(SNAME("doc_source"), EditorStringName(EditorFonts)));
  2893. title->push_font_size(get_theme_font_size(SNAME("doc_source_size"), EditorStringName(EditorFonts)) * 0.9);
  2894. title->push_color(symbol_color);
  2895. title->add_text("(");
  2896. title->pop(); // color
  2897. for (int i = 0; i < help_data.arguments.size(); i++) {
  2898. const ArgumentData &argument = help_data.arguments[i];
  2899. if (i > 0) {
  2900. title->push_color(symbol_color);
  2901. title->add_text(", ");
  2902. title->pop(); // color
  2903. }
  2904. title->add_text(argument.name);
  2905. title->push_color(symbol_color);
  2906. title->add_text(": ");
  2907. title->pop(); // color
  2908. _add_type_to_title(argument.doc_type);
  2909. if (!argument.default_value.is_empty()) {
  2910. title->push_color(symbol_color);
  2911. title->add_text(" = ");
  2912. title->pop(); // color
  2913. title->push_color(value_color);
  2914. title->add_text(argument.default_value);
  2915. title->pop(); // color
  2916. }
  2917. }
  2918. title->push_color(symbol_color);
  2919. title->add_text(")");
  2920. title->pop(); // color
  2921. if (symbol_type == "method") {
  2922. title->push_color(symbol_color);
  2923. title->add_text(" -> ");
  2924. title->pop(); // color
  2925. _add_type_to_title(help_data.doc_type);
  2926. }
  2927. title->pop(); // font_size
  2928. title->pop(); // font
  2929. }
  2930. title->show();
  2931. } else {
  2932. title->hide();
  2933. }
  2934. content->clear();
  2935. bool has_prev_text = false;
  2936. if (!help_data.deprecated_message.is_empty()) {
  2937. has_prev_text = true;
  2938. Ref<Texture2D> error_icon = get_editor_theme_icon(SNAME("StatusError"));
  2939. content->add_image(error_icon, error_icon->get_width(), error_icon->get_height());
  2940. content->add_text(" ");
  2941. content->push_color(get_theme_color(SNAME("error_color"), EditorStringName(Editor)));
  2942. content->push_font(doc_bold_font);
  2943. content->add_text(TTR("Deprecated:"));
  2944. content->pop(); // font
  2945. content->pop(); // color
  2946. content->add_text(" ");
  2947. _add_text_to_rt(help_data.deprecated_message, content, this, symbol_class_name);
  2948. }
  2949. if (!help_data.experimental_message.is_empty()) {
  2950. if (has_prev_text) {
  2951. content->add_newline();
  2952. content->add_newline();
  2953. }
  2954. has_prev_text = true;
  2955. Ref<Texture2D> warning_icon = get_editor_theme_icon(SNAME("NodeWarning"));
  2956. content->add_image(warning_icon, warning_icon->get_width(), warning_icon->get_height());
  2957. content->add_text(" ");
  2958. content->push_color(get_theme_color(SNAME("warning_color"), EditorStringName(Editor)));
  2959. content->push_font(doc_bold_font);
  2960. content->add_text(TTR("Experimental:"));
  2961. content->pop(); // font
  2962. content->pop(); // color
  2963. content->add_text(" ");
  2964. _add_text_to_rt(help_data.experimental_message, content, this, symbol_class_name);
  2965. }
  2966. if (!help_data.description.is_empty()) {
  2967. if (has_prev_text) {
  2968. content->add_newline();
  2969. content->add_newline();
  2970. }
  2971. has_prev_text = true;
  2972. const Color comment_color = get_theme_color(SNAME("comment_color"), SNAME("EditorHelp"));
  2973. _add_text_to_rt(help_data.description.replace("<EditorHelpBitCommentColor>", comment_color.to_html()), content, this, symbol_class_name);
  2974. }
  2975. if (is_inside_tree()) {
  2976. update_content_height();
  2977. }
  2978. }
  2979. void EditorHelpBit::_go_to_help(const String &p_what) {
  2980. EditorNode::get_singleton()->get_editor_main_screen()->select(EditorMainScreen::EDITOR_SCRIPT);
  2981. ScriptEditor::get_singleton()->goto_help(p_what);
  2982. emit_signal(SNAME("request_hide"));
  2983. }
  2984. void EditorHelpBit::_meta_clicked(const String &p_select) {
  2985. if (p_select.begins_with("$")) { // Enum.
  2986. const String link = p_select.substr(1);
  2987. String enum_class_name;
  2988. String enum_name;
  2989. if (CoreConstants::is_global_enum(link)) {
  2990. enum_class_name = "@GlobalScope";
  2991. enum_name = link;
  2992. } else {
  2993. const int dot_pos = link.rfind_char('.');
  2994. if (dot_pos >= 0) {
  2995. enum_class_name = link.left(dot_pos);
  2996. enum_name = link.substr(dot_pos + 1);
  2997. } else {
  2998. enum_class_name = symbol_class_name;
  2999. enum_name = link;
  3000. }
  3001. }
  3002. _go_to_help("class_enum:" + enum_class_name + ":" + enum_name);
  3003. } else if (p_select.begins_with("#")) { // Class.
  3004. _go_to_help("class_name:" + p_select.substr(1));
  3005. } else if (p_select.begins_with("@")) { // Member.
  3006. const int tag_end = p_select.find_char(' ');
  3007. const String tag = p_select.substr(1, tag_end - 1);
  3008. const String link = p_select.substr(tag_end + 1).lstrip(" ");
  3009. String topic;
  3010. if (tag == "method") {
  3011. topic = "class_method";
  3012. } else if (tag == "constructor") {
  3013. topic = "class_method";
  3014. } else if (tag == "operator") {
  3015. topic = "class_method";
  3016. } else if (tag == "member") {
  3017. topic = "class_property";
  3018. } else if (tag == "enum") {
  3019. topic = "class_enum";
  3020. } else if (tag == "signal") {
  3021. topic = "class_signal";
  3022. } else if (tag == "constant") {
  3023. topic = "class_constant";
  3024. } else if (tag == "annotation") {
  3025. topic = "class_annotation";
  3026. } else if (tag == "theme_item") {
  3027. topic = "class_theme_item";
  3028. } else {
  3029. return;
  3030. }
  3031. if (link.contains_char('.')) {
  3032. const int class_end = link.find_char('.');
  3033. _go_to_help(topic + ":" + link.left(class_end) + ":" + link.substr(class_end + 1));
  3034. } else {
  3035. _go_to_help(topic + ":" + symbol_class_name + ":" + link);
  3036. }
  3037. } else if (p_select.begins_with("http:") || p_select.begins_with("https:")) {
  3038. OS::get_singleton()->shell_open(p_select);
  3039. } else if (p_select.begins_with("^")) { // Copy button.
  3040. DisplayServer::get_singleton()->clipboard_set(p_select.substr(1));
  3041. }
  3042. }
  3043. void EditorHelpBit::_bind_methods() {
  3044. ADD_SIGNAL(MethodInfo("request_hide"));
  3045. }
  3046. void EditorHelpBit::_notification(int p_what) {
  3047. switch (p_what) {
  3048. case NOTIFICATION_THEME_CHANGED:
  3049. _update_labels();
  3050. break;
  3051. }
  3052. }
  3053. void EditorHelpBit::parse_symbol(const String &p_symbol) {
  3054. const PackedStringArray slices = p_symbol.split("|", true, 2);
  3055. ERR_FAIL_COND_MSG(slices.size() < 3, "Invalid doc id. The expected format is 'item_type|class_name|item_name'.");
  3056. const String &item_type = slices[0];
  3057. const String &class_name = slices[1];
  3058. const String &item_name = slices[2];
  3059. String visible_type;
  3060. String name = item_name;
  3061. if (item_type == "class") {
  3062. visible_type = TTR("Class:");
  3063. name = class_name;
  3064. help_data = _get_class_help_data(class_name);
  3065. } else if (item_type == "property") {
  3066. if (name.begins_with("metadata/")) {
  3067. visible_type = TTR("Metadata:");
  3068. name = name.trim_prefix("metadata/");
  3069. } else if (class_name == "ProjectSettings" || class_name == "EditorSettings") {
  3070. visible_type = TTR("Setting:");
  3071. } else {
  3072. visible_type = TTR("Property:");
  3073. }
  3074. help_data = _get_property_help_data(class_name, item_name);
  3075. } else if (item_type == "internal_property") {
  3076. visible_type = TTR("Internal Property:");
  3077. help_data = HelpData();
  3078. help_data.description = "[color=<EditorHelpBitCommentColor>][i]" + TTR("This property can only be set in the Inspector.") + "[/i][/color]";
  3079. } else if (item_type == "method") {
  3080. visible_type = TTR("Method:");
  3081. help_data = _get_method_help_data(class_name, item_name);
  3082. } else if (item_type == "signal") {
  3083. visible_type = TTR("Signal:");
  3084. help_data = _get_signal_help_data(class_name, item_name);
  3085. } else if (item_type == "theme_item") {
  3086. visible_type = TTR("Theme Property:");
  3087. help_data = _get_theme_item_help_data(class_name, item_name);
  3088. } else {
  3089. ERR_FAIL_MSG("Invalid tooltip type '" + item_type + "'. Valid types are 'class', 'property', 'internal_property', 'method', 'signal', and 'theme_item'.");
  3090. }
  3091. symbol_class_name = class_name;
  3092. symbol_type = item_type;
  3093. symbol_visible_type = visible_type;
  3094. symbol_name = name;
  3095. if (help_data.description.is_empty()) {
  3096. help_data.description = "[color=<EditorHelpBitCommentColor>][i]" + TTR("No description available.") + "[/i][/color]";
  3097. }
  3098. if (is_inside_tree()) {
  3099. _update_labels();
  3100. }
  3101. }
  3102. void EditorHelpBit::set_custom_text(const String &p_type, const String &p_name, const String &p_description) {
  3103. symbol_class_name = String();
  3104. symbol_type = String();
  3105. symbol_visible_type = p_type;
  3106. symbol_name = p_name;
  3107. help_data = HelpData();
  3108. help_data.description = p_description;
  3109. if (is_inside_tree()) {
  3110. _update_labels();
  3111. }
  3112. }
  3113. void EditorHelpBit::set_description(const String &p_text) {
  3114. help_data.description = p_text;
  3115. if (is_inside_tree()) {
  3116. _update_labels();
  3117. }
  3118. }
  3119. void EditorHelpBit::set_content_height_limits(float p_min, float p_max) {
  3120. ERR_FAIL_COND(p_min > p_max);
  3121. content_min_height = p_min;
  3122. content_max_height = p_max;
  3123. if (is_inside_tree()) {
  3124. update_content_height();
  3125. }
  3126. }
  3127. void EditorHelpBit::update_content_height() {
  3128. float content_height = content->get_content_height();
  3129. const Ref<StyleBox> style = content->get_theme_stylebox(CoreStringName(normal));
  3130. if (style.is_valid()) {
  3131. content_height += style->get_content_margin(SIDE_TOP) + style->get_content_margin(SIDE_BOTTOM);
  3132. }
  3133. content->set_custom_minimum_size(Size2(content->get_custom_minimum_size().x, CLAMP(content_height, content_min_height, content_max_height)));
  3134. }
  3135. EditorHelpBit::EditorHelpBit(const String &p_symbol) {
  3136. add_theme_constant_override("separation", 0);
  3137. title = memnew(RichTextLabel);
  3138. title->set_theme_type_variation("EditorHelpBitTitle");
  3139. title->set_custom_minimum_size(Size2(512 * EDSCALE, 0)); // GH-93031. Set the minimum width even if `fit_content` is true.
  3140. title->set_fit_content(true);
  3141. title->set_selection_enabled(true);
  3142. //title->set_context_menu_enabled(true); // TODO: Fix opening context menu hides tooltip.
  3143. title->connect("meta_clicked", callable_mp(this, &EditorHelpBit::_meta_clicked));
  3144. title->hide();
  3145. add_child(title);
  3146. content_min_height = 48 * EDSCALE;
  3147. content_max_height = 360 * EDSCALE;
  3148. content = memnew(RichTextLabel);
  3149. content->set_theme_type_variation("EditorHelpBitContent");
  3150. content->set_custom_minimum_size(Size2(512 * EDSCALE, content_min_height));
  3151. content->set_selection_enabled(true);
  3152. //content->set_context_menu_enabled(true); // TODO: Fix opening context menu hides tooltip.
  3153. content->connect("meta_clicked", callable_mp(this, &EditorHelpBit::_meta_clicked));
  3154. add_child(content);
  3155. if (!p_symbol.is_empty()) {
  3156. parse_symbol(p_symbol);
  3157. }
  3158. }
  3159. /// EditorHelpBitTooltip ///
  3160. void EditorHelpBitTooltip::_start_timer() {
  3161. if (timer->is_inside_tree() && timer->is_stopped()) {
  3162. timer->start();
  3163. }
  3164. }
  3165. void EditorHelpBitTooltip::_safe_queue_free() {
  3166. if (_pushing_input > 0) {
  3167. _need_free = true;
  3168. } else {
  3169. queue_free();
  3170. }
  3171. }
  3172. void EditorHelpBitTooltip::_target_gui_input(const Ref<InputEvent> &p_event) {
  3173. const Ref<InputEventMouse> mouse_event = p_event;
  3174. if (mouse_event.is_valid()) {
  3175. _start_timer();
  3176. }
  3177. }
  3178. void EditorHelpBitTooltip::_notification(int p_what) {
  3179. switch (p_what) {
  3180. case NOTIFICATION_WM_MOUSE_ENTER:
  3181. timer->stop();
  3182. break;
  3183. case NOTIFICATION_WM_MOUSE_EXIT:
  3184. _start_timer();
  3185. break;
  3186. }
  3187. }
  3188. // Forwards non-mouse input to the parent viewport.
  3189. void EditorHelpBitTooltip::_input_from_window(const Ref<InputEvent> &p_event) {
  3190. if (p_event->is_action_pressed(SNAME("ui_cancel"), false, true)) {
  3191. _safe_queue_free();
  3192. } else {
  3193. const Ref<InputEventMouse> mouse_event = p_event;
  3194. if (mouse_event.is_null()) {
  3195. // GH-91652. Prevents use-after-free since `ProgressDialog` calls `Main::iteration()`.
  3196. _pushing_input++;
  3197. get_parent_viewport()->push_input(p_event);
  3198. _pushing_input--;
  3199. if (_pushing_input <= 0 && _need_free) {
  3200. queue_free();
  3201. }
  3202. }
  3203. }
  3204. }
  3205. void EditorHelpBitTooltip::show_tooltip(EditorHelpBit *p_help_bit, Control *p_target) {
  3206. ERR_FAIL_NULL(p_help_bit);
  3207. EditorHelpBitTooltip *tooltip = memnew(EditorHelpBitTooltip(p_target));
  3208. p_help_bit->connect("request_hide", callable_mp(tooltip, &EditorHelpBitTooltip::_safe_queue_free));
  3209. tooltip->add_child(p_help_bit);
  3210. p_target->add_child(tooltip);
  3211. p_help_bit->update_content_height();
  3212. tooltip->popup_under_cursor();
  3213. }
  3214. // Copy-paste from `Viewport::_gui_show_tooltip()`.
  3215. void EditorHelpBitTooltip::popup_under_cursor() {
  3216. Point2 mouse_pos = get_mouse_position();
  3217. Point2 tooltip_offset = GLOBAL_GET("display/mouse_cursor/tooltip_position_offset");
  3218. Rect2 r(mouse_pos + tooltip_offset, get_contents_minimum_size());
  3219. r.size = r.size.min(get_max_size());
  3220. Window *window = get_parent_visible_window();
  3221. Rect2i vr;
  3222. if (is_embedded()) {
  3223. vr = get_embedder()->get_visible_rect();
  3224. } else {
  3225. vr = window->get_usable_parent_rect();
  3226. }
  3227. if (r.size.x + r.position.x > vr.size.x + vr.position.x) {
  3228. // Place it in the opposite direction. If it fails, just hug the border.
  3229. r.position.x = mouse_pos.x - r.size.x - tooltip_offset.x;
  3230. if (r.position.x < vr.position.x) {
  3231. r.position.x = vr.position.x + vr.size.x - r.size.x;
  3232. }
  3233. } else if (r.position.x < vr.position.x) {
  3234. r.position.x = vr.position.x;
  3235. }
  3236. if (r.size.y + r.position.y > vr.size.y + vr.position.y) {
  3237. // Same as above.
  3238. r.position.y = mouse_pos.y - r.size.y - tooltip_offset.y;
  3239. if (r.position.y < vr.position.y) {
  3240. r.position.y = vr.position.y + vr.size.y - r.size.y;
  3241. }
  3242. } else if (r.position.y < vr.position.y) {
  3243. r.position.y = vr.position.y;
  3244. }
  3245. set_flag(Window::FLAG_NO_FOCUS, true);
  3246. popup(r);
  3247. }
  3248. EditorHelpBitTooltip::EditorHelpBitTooltip(Control *p_target) {
  3249. set_theme_type_variation("TooltipPanel");
  3250. timer = memnew(Timer);
  3251. timer->set_wait_time(0.2);
  3252. timer->connect("timeout", callable_mp(this, &EditorHelpBitTooltip::_safe_queue_free));
  3253. add_child(timer);
  3254. ERR_FAIL_NULL(p_target);
  3255. p_target->connect(SceneStringName(mouse_exited), callable_mp(this, &EditorHelpBitTooltip::_start_timer));
  3256. p_target->connect(SceneStringName(gui_input), callable_mp(this, &EditorHelpBitTooltip::_target_gui_input));
  3257. }
  3258. #if defined(MODULE_GDSCRIPT_ENABLED) || defined(MODULE_MONO_ENABLED)
  3259. /// EditorHelpHighlighter ///
  3260. EditorHelpHighlighter *EditorHelpHighlighter::singleton = nullptr;
  3261. void EditorHelpHighlighter::create_singleton() {
  3262. ERR_FAIL_COND(singleton != nullptr);
  3263. singleton = memnew(EditorHelpHighlighter);
  3264. }
  3265. void EditorHelpHighlighter::free_singleton() {
  3266. ERR_FAIL_NULL(singleton);
  3267. memdelete(singleton);
  3268. singleton = nullptr;
  3269. }
  3270. EditorHelpHighlighter *EditorHelpHighlighter::get_singleton() {
  3271. return singleton;
  3272. }
  3273. EditorHelpHighlighter::HighlightData EditorHelpHighlighter::_get_highlight_data(Language p_language, const String &p_source, bool p_use_cache) {
  3274. switch (p_language) {
  3275. case LANGUAGE_GDSCRIPT:
  3276. #ifndef MODULE_GDSCRIPT_ENABLED
  3277. ERR_FAIL_V_MSG(HighlightData(), "GDScript module is disabled.");
  3278. #endif
  3279. break;
  3280. case LANGUAGE_CSHARP:
  3281. #ifndef MODULE_MONO_ENABLED
  3282. ERR_FAIL_V_MSG(HighlightData(), "Mono module is disabled.");
  3283. #endif
  3284. break;
  3285. default:
  3286. ERR_FAIL_V_MSG(HighlightData(), "Invalid parameter \"p_language\".");
  3287. }
  3288. if (p_use_cache) {
  3289. const HashMap<String, HighlightData>::ConstIterator E = highlight_data_caches[p_language].find(p_source);
  3290. if (E) {
  3291. return E->value;
  3292. }
  3293. }
  3294. text_edits[p_language]->set_text(p_source);
  3295. if (scripts[p_language].is_valid()) { // See GH-89610.
  3296. scripts[p_language]->set_source_code(p_source);
  3297. }
  3298. highlighters[p_language]->_update_cache();
  3299. HighlightData result;
  3300. int source_offset = 0;
  3301. int result_index = 0;
  3302. for (int i = 0; i < text_edits[p_language]->get_line_count(); i++) {
  3303. const Dictionary dict = highlighters[p_language]->_get_line_syntax_highlighting_impl(i);
  3304. result.resize(result.size() + dict.size());
  3305. const Variant *key = nullptr;
  3306. int prev_column = -1;
  3307. while ((key = dict.next(key)) != nullptr) {
  3308. const int column = *key;
  3309. ERR_FAIL_COND_V(column <= prev_column, HighlightData());
  3310. prev_column = column;
  3311. const Color color = dict[*key].operator Dictionary().get("color", Color());
  3312. result.write[result_index] = { source_offset + column, color };
  3313. result_index++;
  3314. }
  3315. source_offset += text_edits[p_language]->get_line(i).length() + 1; // Plus newline.
  3316. }
  3317. if (p_use_cache) {
  3318. highlight_data_caches[p_language][p_source] = result;
  3319. }
  3320. return result;
  3321. }
  3322. void EditorHelpHighlighter::highlight(RichTextLabel *p_rich_text_label, Language p_language, const String &p_source, bool p_use_cache) {
  3323. ERR_FAIL_NULL(p_rich_text_label);
  3324. const HighlightData highlight_data = _get_highlight_data(p_language, p_source, p_use_cache);
  3325. if (!highlight_data.is_empty()) {
  3326. for (int i = 1; i < highlight_data.size(); i++) {
  3327. const Pair<int, Color> &prev = highlight_data[i - 1];
  3328. const Pair<int, Color> &curr = highlight_data[i];
  3329. p_rich_text_label->push_color(prev.second);
  3330. p_rich_text_label->add_text(p_source.substr(prev.first, curr.first - prev.first));
  3331. p_rich_text_label->pop(); // color
  3332. }
  3333. const Pair<int, Color> &last = highlight_data[highlight_data.size() - 1];
  3334. p_rich_text_label->push_color(last.second);
  3335. p_rich_text_label->add_text(p_source.substr(last.first));
  3336. p_rich_text_label->pop(); // color
  3337. }
  3338. }
  3339. void EditorHelpHighlighter::reset_cache() {
  3340. const Color text_color = EDITOR_GET("text_editor/theme/highlighting/text_color");
  3341. #ifdef MODULE_GDSCRIPT_ENABLED
  3342. highlight_data_caches[LANGUAGE_GDSCRIPT].clear();
  3343. text_edits[LANGUAGE_GDSCRIPT]->add_theme_color_override(SceneStringName(font_color), text_color);
  3344. #endif
  3345. #ifdef MODULE_MONO_ENABLED
  3346. highlight_data_caches[LANGUAGE_CSHARP].clear();
  3347. text_edits[LANGUAGE_CSHARP]->add_theme_color_override(SceneStringName(font_color), text_color);
  3348. #endif
  3349. }
  3350. EditorHelpHighlighter::EditorHelpHighlighter() {
  3351. const Color text_color = EDITOR_GET("text_editor/theme/highlighting/text_color");
  3352. #ifdef MODULE_GDSCRIPT_ENABLED
  3353. TextEdit *gdscript_text_edit = memnew(TextEdit);
  3354. gdscript_text_edit->add_theme_color_override(SceneStringName(font_color), text_color);
  3355. Ref<GDScript> gdscript;
  3356. gdscript.instantiate();
  3357. Ref<GDScriptSyntaxHighlighter> gdscript_highlighter;
  3358. gdscript_highlighter.instantiate();
  3359. gdscript_highlighter->set_text_edit(gdscript_text_edit);
  3360. gdscript_highlighter->_set_edited_resource(gdscript);
  3361. text_edits[LANGUAGE_GDSCRIPT] = gdscript_text_edit;
  3362. scripts[LANGUAGE_GDSCRIPT] = gdscript;
  3363. highlighters[LANGUAGE_GDSCRIPT] = gdscript_highlighter;
  3364. #endif
  3365. #ifdef MODULE_MONO_ENABLED
  3366. TextEdit *csharp_text_edit = memnew(TextEdit);
  3367. csharp_text_edit->add_theme_color_override(SceneStringName(font_color), text_color);
  3368. // See GH-89610.
  3369. //Ref<CSharpScript> csharp;
  3370. //csharp.instantiate();
  3371. Ref<EditorStandardSyntaxHighlighter> csharp_highlighter;
  3372. csharp_highlighter.instantiate();
  3373. csharp_highlighter->set_text_edit(csharp_text_edit);
  3374. //csharp_highlighter->_set_edited_resource(csharp);
  3375. csharp_highlighter->_set_script_language(CSharpLanguage::get_singleton());
  3376. text_edits[LANGUAGE_CSHARP] = csharp_text_edit;
  3377. //scripts[LANGUAGE_CSHARP] = csharp;
  3378. highlighters[LANGUAGE_CSHARP] = csharp_highlighter;
  3379. #endif
  3380. }
  3381. EditorHelpHighlighter::~EditorHelpHighlighter() {
  3382. #ifdef MODULE_GDSCRIPT_ENABLED
  3383. memdelete(text_edits[LANGUAGE_GDSCRIPT]);
  3384. #endif
  3385. #ifdef MODULE_MONO_ENABLED
  3386. memdelete(text_edits[LANGUAGE_CSHARP]);
  3387. #endif
  3388. }
  3389. #endif // defined(MODULE_GDSCRIPT_ENABLED) || defined(MODULE_MONO_ENABLED)
  3390. /// FindBar ///
  3391. FindBar::FindBar() {
  3392. search_text = memnew(LineEdit);
  3393. add_child(search_text);
  3394. search_text->set_custom_minimum_size(Size2(100 * EDSCALE, 0));
  3395. search_text->set_h_size_flags(SIZE_EXPAND_FILL);
  3396. search_text->connect(SceneStringName(text_changed), callable_mp(this, &FindBar::_search_text_changed));
  3397. search_text->connect(SceneStringName(text_submitted), callable_mp(this, &FindBar::_search_text_submitted));
  3398. matches_label = memnew(Label);
  3399. add_child(matches_label);
  3400. matches_label->hide();
  3401. find_prev = memnew(Button);
  3402. find_prev->set_flat(true);
  3403. add_child(find_prev);
  3404. find_prev->set_focus_mode(FOCUS_NONE);
  3405. find_prev->connect(SceneStringName(pressed), callable_mp(this, &FindBar::search_prev));
  3406. find_next = memnew(Button);
  3407. find_next->set_flat(true);
  3408. add_child(find_next);
  3409. find_next->set_focus_mode(FOCUS_NONE);
  3410. find_next->connect(SceneStringName(pressed), callable_mp(this, &FindBar::search_next));
  3411. Control *space = memnew(Control);
  3412. add_child(space);
  3413. space->set_custom_minimum_size(Size2(4, 0) * EDSCALE);
  3414. hide_button = memnew(TextureButton);
  3415. add_child(hide_button);
  3416. hide_button->set_focus_mode(FOCUS_NONE);
  3417. hide_button->set_ignore_texture_size(true);
  3418. hide_button->set_stretch_mode(TextureButton::STRETCH_KEEP_CENTERED);
  3419. hide_button->connect(SceneStringName(pressed), callable_mp(this, &FindBar::_hide_bar));
  3420. }
  3421. void FindBar::popup_search() {
  3422. show();
  3423. bool grabbed_focus = false;
  3424. if (!search_text->has_focus()) {
  3425. search_text->grab_focus();
  3426. grabbed_focus = true;
  3427. }
  3428. if (!search_text->get_text().is_empty()) {
  3429. search_text->select_all();
  3430. search_text->set_caret_column(search_text->get_text().length());
  3431. if (grabbed_focus) {
  3432. _search();
  3433. }
  3434. }
  3435. }
  3436. void FindBar::_notification(int p_what) {
  3437. switch (p_what) {
  3438. case NOTIFICATION_THEME_CHANGED: {
  3439. find_prev->set_button_icon(get_editor_theme_icon(SNAME("MoveUp")));
  3440. find_next->set_button_icon(get_editor_theme_icon(SNAME("MoveDown")));
  3441. hide_button->set_texture_normal(get_editor_theme_icon(SNAME("Close")));
  3442. hide_button->set_texture_hover(get_editor_theme_icon(SNAME("Close")));
  3443. hide_button->set_texture_pressed(get_editor_theme_icon(SNAME("Close")));
  3444. hide_button->set_custom_minimum_size(hide_button->get_texture_normal()->get_size());
  3445. matches_label->add_theme_color_override(SceneStringName(font_color), results_count > 0 ? get_theme_color(SceneStringName(font_color), SNAME("Label")) : get_theme_color(SNAME("error_color"), EditorStringName(Editor)));
  3446. } break;
  3447. case NOTIFICATION_VISIBILITY_CHANGED: {
  3448. set_process_unhandled_input(is_visible_in_tree());
  3449. } break;
  3450. }
  3451. }
  3452. void FindBar::set_rich_text_label(RichTextLabel *p_rich_text_label) {
  3453. rich_text_label = p_rich_text_label;
  3454. }
  3455. bool FindBar::search_next() {
  3456. return _search();
  3457. }
  3458. bool FindBar::search_prev() {
  3459. return _search(true);
  3460. }
  3461. bool FindBar::_search(bool p_search_previous) {
  3462. String stext = search_text->get_text();
  3463. bool keep = prev_search == stext;
  3464. bool ret = rich_text_label->search(stext, keep, p_search_previous);
  3465. prev_search = stext;
  3466. if (ret) {
  3467. _update_results_count();
  3468. } else {
  3469. results_count = 0;
  3470. }
  3471. _update_matches_label();
  3472. return ret;
  3473. }
  3474. void FindBar::_update_results_count() {
  3475. results_count = 0;
  3476. String searched = search_text->get_text();
  3477. if (searched.is_empty()) {
  3478. return;
  3479. }
  3480. String full_text = rich_text_label->get_parsed_text();
  3481. int from_pos = 0;
  3482. while (true) {
  3483. int pos = full_text.findn(searched, from_pos);
  3484. if (pos == -1) {
  3485. break;
  3486. }
  3487. results_count++;
  3488. from_pos = pos + searched.length();
  3489. }
  3490. }
  3491. void FindBar::_update_matches_label() {
  3492. if (search_text->get_text().is_empty() || results_count == -1) {
  3493. matches_label->hide();
  3494. } else {
  3495. matches_label->show();
  3496. matches_label->add_theme_color_override(SceneStringName(font_color), results_count > 0 ? get_theme_color(SceneStringName(font_color), SNAME("Label")) : get_theme_color(SNAME("error_color"), EditorStringName(Editor)));
  3497. matches_label->set_text(vformat(results_count == 1 ? TTR("%d match.") : TTR("%d matches."), results_count));
  3498. }
  3499. }
  3500. void FindBar::_hide_bar() {
  3501. if (search_text->has_focus()) {
  3502. rich_text_label->grab_focus();
  3503. }
  3504. hide();
  3505. }
  3506. void FindBar::unhandled_input(const Ref<InputEvent> &p_event) {
  3507. ERR_FAIL_COND(p_event.is_null());
  3508. Ref<InputEventKey> k = p_event;
  3509. if (k.is_valid() && k->is_action_pressed(SNAME("ui_cancel"), false, true)) {
  3510. if (rich_text_label->has_focus() || is_ancestor_of(get_viewport()->gui_get_focus_owner())) {
  3511. _hide_bar();
  3512. accept_event();
  3513. }
  3514. }
  3515. }
  3516. void FindBar::_search_text_changed(const String &p_text) {
  3517. search_next();
  3518. }
  3519. void FindBar::_search_text_submitted(const String &p_text) {
  3520. if (Input::get_singleton()->is_key_pressed(Key::SHIFT)) {
  3521. search_prev();
  3522. } else {
  3523. search_next();
  3524. }
  3525. }